NAME
UR::Object - base class for objects
SYNOPSIS
The constructor adds a new object to the current context:
$elmo = Acme::Puppet->create(
name => 'Elmo',
father => $ernie,
mother => $bigbird,
jobs => [$dance, $sing],
favorite_color => 'red',
);
Plain accessors:
$color = $elmo->favorite_color();
$elmo->favorite_color('blue');
Query the current context:
$existing_obj = Acme::Puppet->get(name => 'Elmo');
@existing_objs = Acme::Puppet->get(
favorite_color => ['red','yellow'],
);
# this will not get elmo because his favorite color is now blue
Save our changes:
UR::Context->current->commit;
Too many puppets:
$elmo->delete;
$elmo->dance; # this will throw an exception now
$elmo = Acme::Puppet->get(name => 'Elmo'); # this returns nothing
Just kidding:
UR::Context->current->rollback; # this is not a database rollback, it's an STM rollback
$elmo = Acme::Puppet->get(name => 'Elmo'); # back again!
DESCRIPTION
UR::Object is the default base class for objects.
The goal of UR::Object is that your application doesn't have to do data management. Just ask for what you want, use it, and let it go. A UR::Object works like a common software object, but it has a "context" which manages its state, references, relationships, in-memory transactions, queries and caching.
UR::Objects support full reflection and meta-programming.
All objects have an "id" property which is a scalar value unique within their class. The id is intended to be as meaningful as possible outside of the application, and usually correlates with a database primary key or has a host/pid for truly application-internal objects. Classes with explicitly defined multiple ID properties will still have an implicit "id" property, and their objects' "id" property will contain a composition of the other ID properties' values.
All UR::Objects are stored in a central hash inside the Context, such that, once created in one part of the application, the object is retrievable in other parts of the application. Objects only leave the application when explictly removed. This means it is not necessary to hold a reference to objects to keep them "alive".
The class provides functionality to get an object by class/id or by class/key-value-list without knowing if the object(s) specified are already "in the application", or must be loaded from the outside.
Objects never directly reference other objects with a Perl reference. References are done by class/id pair, allowing references to objects which are not currently in the application, and supporting the dynamic instantiation of objects on an as-needed basis.
The actual loading and saving of objects is handled by data source classes, supporting varying RDBMS vendors if necessary, handling non-RDBMS objects transparently as needed.
All objects allow callbacks to be set for changes to their properties, supporting the model-view-controller design pattern nicely.
A special object for each subclass of UR::Object is available with meta-data for the class itself. These class objects are of type UR::Object::Type, and are also themselves UR::Objects.
Most other classes in the UR module set derive from UR::Object.
INHERITANCE
UR::ModuleBase Extensions for error, warning, and status messages.
UR::Object This class - general OO features
DERIVED CLASSES
Site-specific classes for logical entity types at the site will derive from UR::Object indirectly, typically via UR::Entity, with the intermediate class providing load/save logic and enforcing database constraints.
CONSTRUCTOR
- create
-
$obj = SomeClass->create(...);
Make a new instance of SomeClass in the current context. This instance will not be visable outside this context until it the context commits its active transaction.
Object instances can also be "constructed" through the Context's object loader as a side effect of calling get
or load
on a class whose data source is external to the program. The implication here is different than the above two methods in that the objects existed outside the application already, but the application is just now aware of them.
METHODS
The examples below use $obj where an actual object reference is required, and SomeClass where the class name can be used.
Finding and destroying things:
- get
-
$obj = SomeClass->get($id); $obj = SomeClass->get(property1 => value1, ...); @obj = SomeClass->get(property1 => value1, ...);
This is the core object retrieval method for all UR::Objects.
It returns one or more objects as decribed by the parameters passed-in.
This method will try SomeClass->is_loaded(@params) as described below, and failing that will try SomeClass->load(@params), hitting the underlying data sources only for objects not already active in the application.
If called in scalar context and more than one object matches the given parameters, get() will raise an exception through
die
. - delete
-
$obj->delete
Takes an object reference an deletes it within the application. This is not removed from the outside database until that database is committed.
Basic identity information:
- class
-
$obj->class
Returns the text string name of the class. Essentially just ref($self) for objects, and $self for classes.
- id
-
$obj->id
A scalar value which uniquely identifies the object within its class. In many cases, where there are super-classes beneath UR::Object, the ID identifies the object within the super-class as well.
Manipulation of object properties:
- (some property name)
-
$obj->$property_name($new_value); $old_value = $obj->$property_name;
There is a method for each property on the object which acts as an accessor. Identity properties are read-only, while non-identity properties are read-write. Assigning an invalid value is allowed, but the object will not be savable until corrected.
- set
-
$obj->set(property1 => $value1, property2 => $value2);
This is a special method for bulk access via key-value pair(s).
Managing the internal set of objects active in the application:
- load
-
SomeClass->load(...) $obj->load()
As a class method, this is typically not called directly, but is called by get() when the specified object(s) are not already in the application. The parameters are the same as those of get(). load() will attempt to load the object from it's storage place outside of the application.
As an instance method, load() is used to force a reload of the object's data from its external data source. If the object has one or more changed properties, and the reloaded data has conflicing changes, load() will raise an exception. This also applies to a get() which loads external data.
- unload
-
$obj->unload SomeClass->unload()
As an instance method, it removes an object from the application. This will fail if the object is changed. As a class method, it will attempt to remove all instances of SomeClass (and its subclasses) from the application.
Objects which have been unloaded are no longer tracked or held by the application's context and are re-blessed to throw execptions if the reference is used.
Attempts to get() the same logical object will cause a new object to be created and made active in the application.
- create_iterator
-
$iter = SomeClass->create_iterator(...);
Returns an object of type UR::Object::Iterator. create_iterator() takes the same arguments as get(), but instead of returning the matching objects, it returns an iterator object with one method, next(). next() will return one object from the resulting set each time it is called, and undef when the results have been exhausted.
UR::Object::Iterator instances are normal object references, not UR-based objects, and obey the same scoping rules as any normal Perl reference.
Other methods
- __meta__
-
$class_obj = $obj->__meta__();
Returns the class metadata object for the given object's class. Class objects are from the class UR::Object::Type, and hold information about the class' properties, data source, relationships to other classes, etc.
- strengthen
-
$obj->strengthen();
UR objects are normally tracked by the current Context for the life of the application, but the programmer can specify a limit to cache size, in which case old, unchanged objects are periodically pruned from the cache. If strengthen() is called on an object, it will effectively be locked in the cache, and will not be considered for pruning.
See UR::Context for more information about the pruning mechanism.
- weaken
-
$obj->weaken();
weaken() is used to give a hint to the object cache pruner that this instance is not going to be used in the application in the future, and should be removed at the earliest chance.
- changed
-
@tags = $obj->changed()
Changes to objects' properties are tracked by the system. If an object has been changed since it was defined or loaded from its external data source, then changed() will return a list of UR::Object::Tag objects describing which properties have been changed.
- invalid
-
@tags = $obj->__errors__()
Check the validity of an object by applying any constraints layed out in the class such as making sure any non-optional properties contain values, numeric properties contain numeric data, and properties with enumerated values only contain valid values.
invalid() returns a list of UR::Object::Tag objects describing each fault the object has.
Subscriptions
Callbacks can be attached to classes, objects and their properties so an application can track changes.
- create_subscription
-
$obj->create_subscription( method => change_type callback => $subref ); SomeClass->create_subscription( id => $obj_id, method => change_type callback => $subref); SomeClass->create_subscription( method => change_type callback => $subref );
Registers a callback to be called when a property of an object is changed.
The
method
param can be any of the class' named parameters, or one of the special changes such as "load", "create" or "delete".In the first case, the callback will be fired when the param_name property of the object is changed. The second case is essentially identical to the first, specifying one specific object ID. In last case, the callback will be fired if param_name is changed among any of SomeClass's instances.
The callbacks will be called with varying parameters depending on the nature of the change. For normal property value changes, the four parameters will be
$obj, $property_name, $old_value, $new_value
. For other change types, the callback will typically get two parameters,$obj, $change_type
. - cancel_change_subscription
-
$obj->cancel_change_subscription($change_type, $callback); SomeClass->cancel_change_subscription($obj_id, $change_type, $callback);
Removes a previously registered subscription to an object or class
Special change types
- create
-
Indicates the object was newly created via create()
- delete
-
Indicates the object was removed via delete()
- load
-
Indicates the object has been loaded into the application, either via define() or by loading it from an external data source.
- unload
-
Indicates the object is being removed from the application, usually via unload().
SEE ALSO
UR, UR::Object::Type, UR::Context
3 POD Errors
The following errors were encountered while parsing the POD:
- Around line 373:
You forgot a '=back' before '=head2'
- Around line 375:
'=item' outside of any '=over'
- Around line 393:
You forgot a '=back' before '=head1'