NAME

OP::ExtID - Overloaded object class for foreign base64-encoded GUIDs

DESCRIPTION

Extends OP::ID.

SYNOPSIS

  use OP::ExtID;

  my $id = OP::ExtID->new("EO2JXisF3hGSSg+s3t/Aww==");

PUBLIC CLASS METHODS

• $class->assert([$query], @rules)

  ExtID() assertions are like pointers defining relationships with other classes, or within a class to define parent/child hierarchy.

  Attributes asserted as ExtID() must match an id in the specified class's database table.

  ExtID() may be wrapped in an Array() assertion for handling one-to-many relationships, at a small performance cost.

  If using MySQL, ExtID also enforces database-level foreign key constraints. In addition to enforcing allowed values on the database level, this will incur a CASCADE operation on DELETE and UPDATE events (meaning if a parent is deleted or updated, the corresponding child rows will be deleted or updated as well; always use parent id in a child object, rather than child id in a parent object).

  The following example illustrates self-referencing and externally referencing attributes with ExtID, using the "Folder" and "Document" desktop paradigm. Each saved object becomes a row in a database table.

  Create a folder class for documents and other folders:

    #
    # File: ExampleFolder.pm
    #
  
    use OP;
  
    create "OP::ExampleFolder" => {
      #
      # Folders can go in other folders:
      #
      parentId => OP::ExtID->assert(
        "OP::ExampleFolder",
        subtype(
          optional => 1
        )
      ),
  
      ...
    };

  A document class. Documents refer to their parent folder:

    #
    # File: ExampleTextDocument.pm
    #
  
    use OP;
    use OP::ExampleFolder;
  
    create "OP::ExampleTextDocument" => {
      #
      # This doc's location in the folder hierarchy
      #
      folderId => OP::ExtID->assert("OP::ExampleFolder"),
  
      #
      # Textual content of the document
      #
      content  => OP::Str->assert(
        subtype(
          columnType => "TEXT"
        )
      ),
  
      # ...
    };

  Caller example which populates some test folders and docs:

    #!/bin/env perl
    #
    # File: somecaller.pl
    #
  
    use strict;
    use warnings;
  
    use OP::ExampleFolder;
    use OP::ExampleTextDocument;
  
    sub main {
      #
      # A parent folder named "General"
      #
      my $folder = OP::ExampleFolder->spawn("General");
      $folder->save();
  
      #
      # A child folder named "Specific"
      #
      my $subfolder = OP::ExampleFolder->spawn("Specific");
      $subfolder->setFolderId( $folder->id() );
      $subfolder->save();
  
      #
      # Put a test document "README" in the parent folder:
      #
      my $readme = OP::ExampleTextDocument->spawn("README");
      $readme->setFolderId( $folder->id() );
      $readme->setContent("Lorem Ipsum Foo! Bla bla bla...");
      $readme->save();
  
      #
      # Put a "Test Text Doc" doc in the sub-folder:
      #
      my $doc = OP::ExampleTextDocument->spawn("Test Text Doc");
      $doc->setFolderId( $subfolder->id() );
      $doc->setContent("Lorem Ipsum Foo! Bla bla bla...");
      $doc->save();
    }
  
    main();

  If a string is specified as a second argument to ExtID(), it will be used as a SQL query, which selects a subset of Ids used as allowed values at runtime. If this query is not given, a flat, immutable list of Ids will be plugged in for allowed values at compile time.

    create "OP::Example" => {
      userId => OP::ExtID->assert(
        "OP::Example::User",
        "select id from example_user where foo = 1"
      ),
  
      # ...
    };

SEE ALSO

This file is part of OP.