NAME

WE::DB::Obj - object database for the WE_Framework

SYNOPSIS

$objdb = WE::DB::Obj->new($root, $db_file);
$objdb = $root->ObjDB;

DESCRIPTION

CONSTRUCTOR new($class, $root, $file [, %args])

new creates a new database reference object (and, if the database does not exist, also the physical database). Usually called only from WE::DB (see there). Parameters are: the $root object (a WE::DB object) and the filename for the underlying database (here, it is MLDBM).

In the optional arguments, further options can be specified:

-serializer => $serializer

The type of the serializer, e.g. Data::Dumper (the default) or Storable.

-db => $db

The type of the database (dbm) implementation, e.g. DB_File (the default) or GDBM_File. Note that other databases than DB_File or GDBM_File have length restrictions, making them unsuitable for using with WE::DB::Obj. However, the CPAN module MLDBM::Sync::SDBM_File workaround the deficiency of the 1K size limit in the standard SDBM_File database.

-locking => $bool

True, if locking should be used. XXX For now, only 0 and 1 can be used, but this should probably be changed to use shared and exclusive locks.

By default, there is no locking. If locking is enabled and the database type is DB_File, then DB_File::Lock will be used. For other database types, no locking is implemented.

-readonly => $bool

Open the database read-only. This is the same as specifying O_RDONLY. By default it is opened read-write and the database is created if necessary (O_RDWR|O_CREAT).

-writeonly => $bool

If true, then a database will not be created if necessary. This is the same as specifying O_RDWR.

-connect => $bool

If true, connects to the database while constructing the object. Otherwise the connection will be made automatically before each operation. Also, the methods connect and disconnect can be used for connecting and disconnecting from the database.

Normally, long running processes (servers or mod_perl processes) should specify -connect => 0 and use the auto-connection feature or manually connect()/disconnect(). So database changes are propagated immediately.

The default of the -connect option is true.

DESTRUCTOR DESTROY

Called automatically. Destroys the tied database handle.

METHODS

Please see also WE::DB::ObjBase for inherited methods.

connect

disconnect

init

Initialize the database to hold meta data like _root_object or _next_id. Usually called only from WE::DB.

delete_db_contents

Delete all database contents

root_object

Return the root object.

is_root_object($objid)

Return true if the object with id $objid is the root object.

_next_id

Increment and get the next free id. The internal id counter is always incremented, regardless whether the new id will be used or not.

_get_next_id

Only get the next free id, without incrementing it.

_create_stored_obj

Create a new internal stored object.

_store_stored_obj($stored_object)

Store the internal stored object.

_store_obj($object)

Store the object. Please note that there is a difference between a stored object (holding additional data like children, parents etc.) and the mere object.

_get_stored_obj($object_id)

Get a stored object.

get_object($object_id)

Get an object by id.

exists($object_id)

Return true if the object exists. Parameter is the object id.

children_ids($object_id)

Return a list of the children ids of this object. If the object does not exist or the object has not children, return an empty list.

parent_ids($object_id)

Like children_ids, but return parent ids instead.

version_ids($object_id)

Like children_ids, but return version ids instead.

find_links($target_id)

Find links with the $target_id as target.

unlink($object_id, $parent_id, %args)

Remove the given parent link from the object. If there is no parent link anymore, remove the whole object.

Remaining arguments are passed to the remove method (see there).

link($object_id, $folder_id)

Link an object to a folder. This can be used to create multiple links. It is possible to create multiple links from one object to another --- this behaviour may change XXX. See also "BUGS".

remove($object_id, %args)

Remove the object $obj_id and all links to this object uncoditionally.

If -links => "unhandled" is specified, then links to this object won't get removed. This is dangerous, and needs an additional we_fsck run afterwards. This option is useful if a mass-delete should be done.

insert_doc(%args)

Insert a document. The following arguments should be given:

-content: a string to the content or
-file:    the filename for the content
-parent:  the id of the parent

Other arguments will be used as attributes for the object, e.g. -ContentType will be used as the ContentType attribute and -Title as the title attribute. Note that these attributes are typically starting with an uppercase letter.

Return the generated object.

insert_folder(%args)

Insert a folder. The following arguments should be given:

-parent:  the id of the parent

Return the generated object.

insert($object, %args)

General method for inserting objects. You will mostly use either insert_doc or insert_folder.

Arguments: -parent for parent object.

Return the generated object.

content($object_id)

Get the content for the given object.

replace_content($object_id, $content)

Replace the content of an existing object. Return the object itself.

flush

Flushes all changes, so they are visible to other processes. This is done automatically on end of the program or if the object is destroyed.

replace_object($object)

Replace the given object. Argument is an object. This object should contain the valid id. Return the object itself.

is_ancestor($object_id, $ancestor_id)

Return true if $ancestor_id is an ancestor of $object_id.

copy($object_id, $folder_id, %args)

Copies the object identified by $object_id to the folder identified by $folder_id. Both the object metadata and the content are copied. Folders are copied by default recursively. To only copy the folder object, use -recursive => 0 in the %args parameter hash.

Return the copied object. If there is a recursive copy, then return a list of copied objects. In this list, the first object is the copied top folder. In scalar context, always return only the first (or only) copied object.

Version information is never copied (yet).

ci($object_id, %args)

Check in the current version of the object with id $object_id. You can use additional parameters:

-log => $log_message

Specify a log message for this version (recommended). -comment is an alias for -log.

-number => $version_number

Normally, the version number is just incremented (e.g. from 1.0 to 1.1). If you like, you can specify another version number. There are no checks for valid version numbers (that is, you can specify more than one number, invalid formatted version numbers etc). -version is an alias for -number.

-trimold => $number_of_versions

If set to a value greater 0, then delete old versions. Set $number_of_versions specify the number of versions you want to keep. With -trimold => 1, all but the newest version will be wiped out.

Return the checked-in objects. The original object is set to not dirty.

trim_old_versions($object_id, [ -trimold => $number | -all => 1 ])

Trim the last $number versions of object $object_id. If -all is used instead, then trim all old versions. -all and -trimold are mutually exclusive.

co($object_id [, -version => $version_number])

NYI.

Check out the object with the version number $version_number. If version number is not given, then check out the latest version. If the version number is not given and there are no versions at all, then an exception will be thrown. Please note that a check out will override the current object, so you probably should do a ci first. No locking is done (yet).

move($object_id, $parent_id, %args)

Move the object with $object_id and linked to the parent $parent_id to another position or destination. If $parent_id is undef, then the first found parent is used. If there are multiple parents, then it is better to specify the right one. The %args portion may look like this:

-destination => $folder_id

Move the object to another folder. You can also use -target as an alias for -destination.

-after => $after_object_id

Leave the object in the same folder, but move it after the object with the id $after_object_id. If there is no such object in the folder, then an exception is raised.

-before => $before_object_id

Same as -after, but move the object before the specified object.

-to => "begin" | "end"

Move the object to the beginning or end of the folder. For "begin", you can also use "first" and for "end", you can use "last".

Return nothing. On error an exception will be raised.

dump(%args)

Dump object structure as a string. Possible options:

-root => $object_id

Specify another object to start dumping from. If not specified, start dumping from root object.

-versions => $bool

If true, then version information is also dumped.

-attributes => $bool

If true, then attribute information is also dumped.

-children => $bool

Recurse into children. This is by default true.

-callback => $sub

A reference to a callback which can dump additional code. The subroutine will get the following key-value pairs as arguments:

-obj

The current object

-level

The current level

-indentstring

An indentation string

The subroutine should return a string. See content_callback in the we_dump script for an example.

depth($obj_id)

Get the minimum and maximum depth of the object. There are multiple depths, because the object can be in multiple parents with different depths.

($min_depth, $max_depth) = $objdb->depth($obj_id);

PATH_SEP

The default path separator is "/".

pathname2id($pathname [, $parent_obj])

Return the object id for the matching "pathname". There are no real pathnames in the WE_Framework, so a dummy pathname is constructed by the titles (english, if there are multiple). PATH_SEP is used as the path separator.

If $parent_obj is given as a object, then the given pathname should be only a partial path starting from this parent object.

Return undef if no object could be found.

pathname($object_id [, $parent_obj, %args])

For the object $object_id, the virtual pathname (as described in pathname2id) is returned.

If $parent_obj is given as a object, then the returned pathname is only a partial path starting from this parent object.

Possible key-values for %args:

-lang => $lang

Use the specified language $lang rather than the default language (en) for title composition.

get_released_children($folder_id)

Return recursive all folders and released children of the given folder $folder_id as an array of objects.

get_released_object($object_id)

Return the last released version for $object_id. If there is no released version yet, return undef.

is_active_page($obj)

Return true if the object $obj is active, that is, the release state is not inactive and TimeOpen/TimeExpire does not apply.

BUGS

For some methods, there are cycle test missing. Therefore it is possible that methods cause endless loops, if links are causing cycle loops! Please think before using link()!

AUTHOR

Slaven Rezic - slaven@rezic.de

SEE ALSO

WE::DB, WE::DB::ObjBase.