NAME

Podius::Component - virtual superclass of business objects

SYNOPSIS

Must not be used in user applications, use subclassed component modules instead.

DESCRIPTION

To write.

REQUIREMENTS

the Exception manpage, the Debug manpage, the Podius::Property manpage, the Podius::Property::HiddenAutoVComponent manpage, the Podius::Property::HiddenAutoScalar manpage, the Podius::Property::AutomanagedTime manpage, the Podius::Exceptions manpage, the Data::NeatFormat manpage.

CONSTRUCTORS

new_without_properties

description
Class constructor. Used before component deserialization.

parameters
Class name like any constructor.

Optionally hash of initializing fields may be specified. Currently its keys can be 'id', 'revision' and 'root'.

returns
New formed component reference.

new

description
Class constructor.

parameters
Class name like any constructor.

Optionally hash of initializing fields may be specified. Currently its keys can be 'id' and 'root'.

The Component property 'id' is initialized by this optional parameter or undef. If specified, id must be unique in component class. Usage of ids is not mandatory for non-persistent components.

returns
New formed component reference.

new_from_serialized

description
Class constructor. Can be used for component deserialization.

It is BROKEN for now.

See also serialize method.

parameters
Gets class name and component serialized string and constructs the component. Optionally hash of initializing fields may be specified. Currently its keys can be 'id', 'root' and 'container'.

returns
New formed component reference.

METHODS

init_from_serialized_properties

description
Initializes component properties of the component from given property strings.

parameters
Gets array of property elements, each property element is array [property_name, property_string].

Optional revision of the provided properties can be given.

returns
None.

uninit_properties

description
Uninitializes given component properties of the component.

parameters
Gets array of property names.

returns
None.

is_abstract

description
Some component classes in the inheritance hierachy may be marked ``abstract'', using $IS_ABSTRACT variable. Such component classes may have no instances.

This is a class method (obviously if you have an instance in hand then its class is not abstract).

returns
1 if this component class is abstract, and 0 otherwise.

get_id, id

description
Component id is a static id, given to the component in its constructor by persistence component manager. It is undefined for non-persistent environment.

This method returns the unique component id.

Uniqueness is defined by virtual is_access_super_class method of component class. By default, all ids are unique within all component sub-classes.

returns
A number, representing component id.

get_revision, set_revision

description
The component revision is usually an integer, which is increased by 1 on save by persistence component manager. It's undefined in non-persistent environment.

The component revision can be used in concurent environment to avoid inconsistency. Conflicts can be solved using merge method.

These methods return or set the component revision. You must usually not use them.

parameters
None for getter, a new revision for setter.

returns
A number, representing the component revision.

as_string

description
Returns ident string, uniquely representing the component, formated for the printing.

This method is used in overloaded stringify "" operation.

returns
String of the form ``[Type, id]'', like '[Article, 12]'.

equals

description
Compares itself with the given component.

parameters
  * component (or array ref of the form [component_type, component_id])
returns
Boolean.

serialize_properties

description
Used for property serialization. Returns array of named property strings, from which the component properties can be restored later by init_from_serialized_properties constructor.

parameters
 * optional flag - 0: include all properties (default), 1: only modified
returns
Array of property elements. Each property element is array [property-name, property-string].

Where property-string may be arrayref too.

serialize

description
Can be used for component serialization.

It is BROKEN for now.

Returns string, from which the component object can be restored later by new_from_serialized constructor.

returns
Scalar, representing component serialization string.

merge

description
This virtual method is responsible for merging the component with other specified one.

If the callback is specified it is called everytime the properties can't be automatically merged. The callback gets 4 parameters: old and new components, old and new properties (this and the specified one). The callback must return 1 on successful merging or 0 on failure. For example, in the GUI implementation an interactive callback can ask the user about the policy of merging (keep this local - 1 or switch to a new - 2) and then call the property method merge() with the this non zero policy and return its result.

parameters
 * new component
 * optional policy: 0 - pure merge (default), 1 - keep old, 2 - keep new
 * optional callback for the failed property merge
returns
1 on success. Otherwise throws Exception::Podius::CantMergePropertyError.

has_property

description
Answers either given property name is existing component property.

parameters
Scalar - property name.

returns
Boolean; 1 - if given property exists, otherwise 0.

load_properties

description
Loads specified unloaded properties (valid only in the persistent environment).

parameters
Optional array ref of property names. By default all properties are taken.

returns
None.

unload_properties

description
Unloads specified loaded properties (valid only in the persistent environment).

parameters
Optional array ref of property names. By default all properties are taken.

returns
None.

get_property

description
Returns contained property, given by its name.

parameters
Scalar - property name.

returns
Subclassed reference of class Podius::Property.

add_observer_provider

description
Adds observer implementer to component observable(s). If it is already exists there it will not be added.

parameters
        * observer provider (object ref)
        * component observable(s) (string or array ref of strings)
returns
None.

delete_observer_provider

description
Deletes observer implementer from all matched component observables.

parameters
        * observer provider (object ref)
returns
None.

notify_observers

description
Notifies all observers of given observable. Name of observer in observer provider object is evaluated in such manner: observable ``name with spaces'' - observer $provider->name_with_spaces().

parameters
        * observable (string)
        * additional parameters to observer (first is always the component)
returns
None.

add_property_type_observer_provider

description
Adds observer provider to property observable(s) of all owned properties of given type.

parameters
        * property super type
        * observer provider (object ref)
        * property observable(s) (string or array ref of strings)
        * optional flag: 1 (default) - process all properties, 0 - only loaded
returns
None.

add_conditional_property_observer_provider

description
Adds observer implementer to conditional property observable(s). Currently there is global list for all component types.

Keys of condition hash can be: 'name', 'type', 'name-regexp'.

NOTE: currently second parameter as array is not supported. Use multiple calls for each observable.

If given conditional property observable entry already exists, it will not be added.

parameters
        * observer provider (object ref)
        * property observable(s) (string or array ref of strings)
        * condition hash
example
        $component->add_conditional_property_observer_provider(
                $tree_viewer,
                'property changed',
                { name => 'name' }  # or:  { type => 'ComponentCollection' }
        )
returns
None.

delete_conditional_property_observer_provider

description
Deletes observer implementer from all matched conditional property observable entries.

parameters
        * observer provider (object ref)
returns
None.

notify_conditional_property_observers

description
Notifies all satisfying conditional property observers. Name of observer in observer provider object is evaluated in such manner: property observable ``any name'' - observer $provider->component_any_name().

parameters
        * property observable (string)
        * property (instance of Podius::Property)
        * additional parameters to observer (first are component and property)
returns
None.

is_modified

description
The component is modified, if any of the properties is modified.

returns
Returns true if the component is modified.

Actually returns the modified count - number of modified properties, since last reseting.

set_modified

description
Changes modified flag (count) of the component (default is increase).

parameters
        * flag:
                0 - reset modified count (set to 0 - unmodified)
                1 - increase modified count
        #       -1 - decrease modified count
        * optional flag; 1 (default) if it is first report of such change
        * optional flag; 1 (default) if last_modified must be updated
returns
modified count.

lock

description
Sets component locked. This actually increases global counter of locks.

returns
The counter of having locks without this lock.

unlock

description
Sets component unlocked. This actually decreases global counter of locks. Exception is thrown, if the counter becomes negative.

returns
The counter of remained locks.

get_lock_count

description
The component is locked, if it got more lock messages than unlock ones. This method can be used by component managers, which must try not to delete locked component from memory, until it gets unlocked.

returns
The number of component locks.

set_lock_count

description
Explicitly sets number of locks for the component. This method must never be called in most of cases.

parameters
The number of locks to set.

get_constant

description
Returns constant with given parameters from root configuration. Delegates this call to root component's method get_cfg_constant (with component inserted as the first parameter), if root exists.

returns
Constant value, if root defined, otherwise undef.

get_root

description
Root component usually is set once on component creation.

returns
Reference to the component, which is root (or undef, if not defined such).

set_root

description
Sets root for this component. Usually is set once on component creation.

returns
Reference to the component, which is root for this component.

set_container_collection

description
Sets container component and its collection name for this component. Set/unset on adding/deleting this component from its container collection.

parameters
        * component (container)
        * scalar (collection property name)
returns
None.

get_property_types

description
Provides an information about component properties and their order. You probably don't need to touch this method in subclasses, overwrite get_own_property_types instead.

Caches result for any component instance of the same type.

returns
Array of the form: 
        [ [property_name => property_type, additional_params*]* ]

get_property_names

description
Provides an information about component property names and their order.

Caches result for any component instance of the same type.

returns
Array of form [ property_name* ].

get_property_names_of_type

description
Returns all property names of the specified property type in the natural order.

Caches result for any component instance of the same type.

parameters
scalar - property supertype to match against

returns
Array of form [ property_name* ].

exclude_property_names_of_type

description
Returns all property names that are not of the specified property type(s).

parameters
  * optional arrayref of property names to examine
    (defaults to result of B<get_property_names>)
  * one or more property type to exclude
returns
Array of form [ property_name* ].

get_read_only_property_names

description
This class method is intended to be overriden by subclasses, returns all property names, which should be shown read-only in all kinds of GUI. This is in addition to properties of type which should be normally shown read-only, like Constant or Automanaged.

By default returns an empty list.

parameters
none

returns
Array of form [ property_name* ].

is_property_read_only

description
This class method is intended to be used by all kinds of GUI to determine whether to show a property read-only or read-write.

This usually does not need be overridden. The default behaviour is this: property is read-only if it inherits from Constant or Automanaged or returned in get_read_only_property_names.

parameters
scalar - property name

returns
1 if property is read-only, 0 otherwise.

get_hidden_property_names

description
This class method is intended to be overriden by subclasses, returns all property names, which should be hidden in all kinds of GUI. This is in addition to properties of type which should be normally hidden, like Hidden.

By default returns an empty list.

parameters
none

returns
Array of form [ property_name* ].

is_property_hidden

description
This class method is intended to be used by all kinds of GUI to determine whether to show or hide a property.

This usually does not need be overridden. The default behaviour is this: property is hidden if it inherits from Hidden or is returned in get_hidden_property_names.

parameters
scalar - property name

returns
1 if property is hidden, 0 otherwise.

get_cloneable_property_names

description
This class method is intended to be used when cloning component (or copying its individual properties). It returns names of properties that are considered safe to be cloned.

By default, property types Automanaged and AbstractComponentCollection are ignored. This behaviour may be overridden in subclasses.

parameters
none

returns
Array of form [ property_name* ].

get_merge_forced_property_names

description
This class method is used when merge is done. This happens when some other concurrent process modified the stored component after the local component properties were loaded, and it was modified locally too.

It returns names of the properties that should not be normally merged (with potential conflict), but instead the current (local) property value of which should be forced.

By default, no properties are forced. May be overridden in subclasses.

parameters
none

returns
Array of form [ property_name* ].

import_properties

description
Copy all given properties from the given component (that should be compatible, i.e. of the same type or strongly of a supertype of this component).

By default, all properties returned by get_cloneable_property_names are imported (copied).

parameters
  * component to import properties from
  * optional arrayref of property names
returns
This component (self).

update_properties

description
Given the hash of property names with their values, set the given properties with these new values.

parameters
  * flat hash of property names and values for setting
returns
This component (self).

get_cache

description
Returns component cache object this component is stored in, or undef.

parameters
none

returns
the Podius::Persistence::ComponentCache manpage object.

get_container_iterator

description
More or less a shortcut to $self->container->$container_collection_name(), but quietly returns undef if there is no container. It also optionally smartly sets the index in the iterator if requested.

params
Optional seek_idx_offset (default is undef, meaning don't seek, i.e. don't change the default iterator's index 0).

If 0 is passed, then the index of the returned iterator is set to point to this contained component, that is useful in situations when immediate access to next/previous components are needed (see get_next, get_prev and other iterator's methods). Moreover, if -1 or +1 or similar index offset is passed, then the index is directly set to point to the previous or next component in the collection.

returns
the Podius::Persistence::ComponentIterator manpage object.

clone

description
Creates a new component of the same type in either persistent or transient environment (i.e. with component cache or without) and initializes its properties using import_properties.

If the original component has a container (parent), then a newly created component is added to the same container collection the original component belongs to (see get_container_iterator). However it may be added to a different container_iterator instead, if specified.

On recursive, the clone is repeated for all children, so effectively a new parallel component tree is created, repeating the original one.

Argument keys may be: ``id'' - request the specific id for the (top-most) cloned component; ``type'' - request the different type for the (top-most) cloned component (that is a sub-type of the original component, if so); ``id_offset'' - use this integer offset to calculate ids of cloned comonents relative to the original ids; ``id_step'' - use this integer to increase ids of new components (by default the step is usually 1). These arguments are all dangerous and are not recommended, and only in effect in persistent environment.

Subclasses may define more useful arguments. For example, the Podius::Component::Multilingual manpage supports additional one: ``language''. So one may clone component trees for new languages, i.e. add a new tree of Vietnamese components parallel to English components (and language_clones in all components will be updated accordingly).

parameters
  * recursive (optional boolean, default: 0)
  * container_iterator (optional ComponentIterator instanse)
  * args (in non-referenced hash form)
returns
A newly created component of the same type.

create_child

description
Creates a child component of the specified type, initializes it if needed and adds it to the specified component collection. The component type should be acceptable by the component collection.

See the Podius::Persistence::ComponentCache manpage for create_component method and the Podius::Persistence::ComponentIterator manpage for add method.

Also see update_properties.

parameters
  * component collection name to add new child to
  * component type of the child (or another component to be used
    to initialize the new component from)
  * flat hash of property names and values for initialization
returns
A newly created child component.

example
  my $child = $component->create_child('articles', 'Review',
    name => 'Just a test');

foreach_child

description
Executes the given code for each contained component recursivelly.

Each component collection accessed and delegated foreach method.

See the Podius::Persistence::ComponentIterator manpage for foreach method.

parameters
  * code ref (anonymous sub) or function name (say, 'delete')
  * optional flag - 1 means process all childs recursively, 0 (default)
means process only the direct children, negative means levels to process
returns
Whatever the foreach iterator method returns.

examples
  my $child_names = $component->foreach_child(sub {$_->name});
  # delete all children recursivelly
  $component->foreach_child("delete", 1);

get_concrete_sub_class_list

description
See description of get_concrete_sub_type_list and s/type/class/.

get_concrete_sub_type_list

description
This method returns all concrete component types for them this component type is a super-type. Only non-abstract component types are returned. The abstractness is controlled by the class variable $IS_ABSTRACT.

For example we have such component class sub-tree:

  Product (abstract)
    |--- Book (abstract)
    |      |--- ChildrenBook
    |      `--- FantasyBook
    `--- Phone

Then, Product->get_concrete_sub_type_list returns: [ 'ChildrenBook', 'FantasyBook', 'Phone' ]

The order of the returned component types is controlled in Podius::UserComponentClasses package.

returns
Array ref of form [ sub_type* ]. The first in the array is usually the type of this class (as returned by get_type method) unless it is abstract.

get_access_super_class_list

description
See description of get_access_super_type_list and s/type/class/.

get_access_super_type_list

description
This method is used in persistent environment and returns subset of types of superclasses in the inheritance path, which can be used to access this class instanses.

By default, returns all supertypes in the inheritance path. This method may be overridden.

Each Component subclass has inheriting path from the Base Component to itself. But some superclasses can be pure virtual or for other reasons have no instanses, so we don't want the ability to distinguish them by ids. In this case this method can return types of not all superclasses for given class.

For example we have such component class tree:

  Base (type for Podius::Component superclass)
    `--- Publishable
           |--- Edition
           |--- Section
           `--- Article
                  `--- ArticleWithAddition
                         |--- ArticleWithReport
                         `--- ArticleWithComment

ArticleWithReport->get_access_super_type_list can return [ 'Article', 'ArticleWithReport' ] instead of default [ 'Base', 'Publishable', 'Article', 'ArticleWithAddition', 'ArticleWithReport' ]

which can somewhat reduce persistence access time and place. In this case we suppose all Component subclasses do not include 'Base' and 'Publishable' in this method and never get_component('Base', $id) is called, only get_component('Article', $id) or get_component('ArticleWithReport', $id).

returns
Array ref of form [ super_type* ]. This is a read-only array. The last in the array is the type of this class (as returned by get_type method).

get_access_super_type_owning_property

description
Returns super component type, where given property is explicitly owning. This type is one of the access-super-types, returning by get_access_super_type_list method.

parameters
Scalar - property name.

returns
Super type of this component (scalar) or undef if the component has no such property.

get_property_types_by_names

description
Provides subset of types, which get_property_types method provides. Returns only types of given properties.

parameters
        * array ref of property names
returns
Array of the form: 
        [ [property_name => property_type, additional_params*]* ].

get_proxy_group_entries

description
Provides definition of property groups. This will be one, set by method set_proxy_group_entries or default definition defined by get_default_proxy_group_entries.

This method needs not to be overwritten. Overwrite get_default_proxy_group_entries instead. This is more or less private method.

returns
Array of group definitions of the form: 
        [ [property_name*], [pull_group_num*] ]

set_proxy_group_entries

description
Sets user-defined definition of proxy property groups. Must be called at the very beginning, before first usage of proxies, because all proxy data is cached.

parameters
Array of group definitions of the form: 
        [ [ [property_name*], [pull_group_num*] ]* ]

get_type

description
This method provides type (scalar) for this component as used in applications (or in gui) for representation of this component type, like ``Edition''. Default is perl type without ``Podius::Component::'' prefix. ``Base'' is used for Podius::Component superclass. If overwritten in subclass, it must call register_type method.

returns
Scalar, representing component type.

get_class_by_type

usage
        my $class = Podius::Component::get_class_by_type($type);
description
This is static method, translates from component type to component class, the pair to get_type method. If called after it, the type is already registered and taken from appropriate place, otherwise default translation is adding ``Podius::Component::'' prefix. ``Base'' is translated to Podius::Component.

parameters
        * component type to be translated to component class
returns
Scalar, representing perl component class.

isa_type

usage
        die "Fatal error" unless $component->isa_type('Publishable');
        die "Unsupported" unless $component->isa_type('Multilingual');
description
Similar to UNIVERSAL::isa method, but gets component type, not component class.

Note: $component->isa_type('Base') is always true for any component and is equivalent to $component->isa('Podius::Component').

parameters
        * component super-type
returns
Boolean value; true if the component is a sub-type of given super-type.

get_property_class_by_type

description
This method translates from component property type to property class.

returns
Scalar, representing perl property class.

get_property_class_by_name

description
This method translates from component property name to property class.

returns
Scalar, representing perl property class.

get_property_type_by_name

description
This method translates from component property name to property type.

returns
Scalar, representing component property type.

In the list context returns (property type, property type parameters).

get_property_label_by_name

description
This method is designed to return human-redable property names as opposite to perl identifier names. These nice names may be used as labels in GUI.

The default algorithm is to convert property name ``container_collection_name'' or ``containerCollectionName''`` to label ''Container Collection Name``.

In the future there will be some mechanism to explicitly specify property labels in component types.

returns
Scalar for property label.

get_own_property_types

description
Provides an information about own component properties (additional, non included in superclasses) and their order. This is protected virtual method, must be overwritten in subclasses.

returns
Array of form [ [ property_name => property_class ]* ].

get_default_proxy_group_entries

description
Provides default definition of proxy property groups. All non-specified properties will be automatically included in the last (auto-created) proxy group.

If empty array is returned, then all properties are in first (num = 0) proxy group.

This is virtual method. Subclass may define its own different default proxy groups.

The default implementation of this method is having one proxy group including all base properties, with all other properties falling to the second group.

The method set_proxy_group_entries may be used to dynamically set different proxy groups than the default ones defined by this method.

returns
Array of group definitions of the form: 
        [ [ [property_name*], [pull_group_num*] ]* ]

get_name

description
Virtual method. May be used for naming components in GUI.

By default, name property is returned. Subclasses may overwrite this behavior with some logic, like for example: use author property if defined, otherwise 30 chars of subject property if defined, otherwise fallback to name property.

returns
Name for this component.

get_path_components

description
Returns all components in the tree path from the main component to this component.

Components are arranged in the tree using parent-child relation, that is implemented using ComponentCollection property in one direction and container with container_collection_name properties in the opposite direction.

returns
Non-empty array-ref of components.

get_path_components_of_type

description
Just like get_path_components, but gets component type by which to filter.

returns
Possibly empty array-ref of components.

get_parent_components

description
Returns all components in the tree path from the main component to the component's parent.

See also get_path_components.

returns
Possibly empty array-ref of components.

get_parent_components_of_type

description
Just like get_parent_components, but gets component type by which to filter.

returns
Possibly empty array-ref of components.

get_main_component

description
Returns the main component (the one with no futher container).

See also get_path_components.

returns
Instance of type the Podius::Component manpage.