NAME
    XAO::DO::FS::Hash - Core data class for XAO::FS

SYNOPSIS
     my $data=XAO::Objects->new(objname => 'FS::Hash');

     $data->put(aaa => 123);

     my $aaa=$data->get('aaa');

DESCRIPTION
    This is a core data class for XAO Foundation Server (see the XAO::FS
    manpage). All data classes are based on FS::Hash and for that matter
    FS::Hash can be considered pure virtual class which you would never want
    to use directly.

    A data object can contain arbitrary number of named single-value
    parameters and arbitrary number of list objects. Whenever you need more
    then one count of something you will have to create a list object to
    store those things. For example if you only have one shipping address
    per customer - you can store it as a couple of properties in Customer
    object, but if you want a customer to have an address book - create list
    object named Addresses and store addresses inside of it.

    Any data object at any given time can be in either attached state
    (stored in some List and connected to the database) or in detached state
    (when it is not connected to the database layer all manipulations on
    object's properties only change memory).

    Detached data object can be at any time re-attached to a container or
    stored under different ID. That allows a developer to have increased
    performance when required by detaching an object and then using
    in-memory copy.

    When an object is attached all data manipulations are done directly on
    database and never cached. Reasonable measures should be taken by
    developer to ensure that it is safe to re-attach an object to the
    database because the content of the object would replace current
    database content. Object server does not try to map any changes that you
    make to the database back to the detached object. Once detached the
    object is on its own.

    Here is the entire API that is available in all objects based on the
    FS::Hash class. It is not recommended to override or extend any of these
    methods unless stated otherwise in method description. Methods are
    listed in alphabetical order.

    add_placeholder (%)
        Modifies database scheme by adding new possible parameter name into
        the object. After you call this method you can call put() and get()
        on the name you have added.

        The operation can take some time especially if you have a lot of
        objects of that type in the database because it have to modify
        database tables and add new field.

        Arguments are (alphabetically):

        class
            Only makes sense for 'list' type - sets the name of class for
            the objects that would be contained in the list. That class have
            to exist and be available for object loader at the time of the
            call.

        connector
            Optional name of the key that would refer objects in the list to
            the object they are contained in. Default is 'parent_unique_id',
            you can change it to something more meaningfull so that it would
            make sense for somebody looking at the plain SQL tables.

        index
            Optional parameter that when set to non-zero value suggests that
            you are going to use this field in searches a lot. This works
            especially good on `real' and `integer' fields when you later
            search on them using ranges or equivalence.

            For text searches it is usually better to make a field of type
            `words' then making an index on it. Indexing text fields works
            great mostly on 'eq' and 'ne' search operators, not 'ws' or
            'wq'.

            Regardless of your use of indexes searches are guaranteed to
            produc equal results. Indexing can only improve performance or
            decrease it when used incorrectly.

        key Name of the key that would identify objects in the list.
            Required if you add a 'list' placeholder.

            When possible it is recommended to name the key as the class
            name or some derivative from it with '_id' suffix. If you add
            Orders list placeholder it is recommended to call the key
            'order_id'.

        maxlength
            Maximum length for 'text' type in characters. If later on you
            will try to store longer text string into that field an error
            will be thrown. Default is 100.

        maxvalue
            Maximum possible value for `integer' and `real' properties,
            inclusive. Default is 2147483647 for integer property if
            minvalue is negative and 4294967295 if minvalue is zero or
            positive.

            Depending on database driver used you may inmprove performance
            when you use minimal possible ranges for your values. This is
            true for MySQL at least.

        minvalue
            Minimum possible value for `integer' and `real' properties,
            inclusive. Default is -2147483648 for integer property. If you
            use positive value or zero for integer property you're
            converting that property to unsigned integer value effectively.

        name
            Placeholder name -- this is the name you would then use in put()
            and get() to access that property.

            It is recommended to name single-value properties in
            all-lowercase with underscores to separate words (like
            "middle_name") and name lists in capitalized words (like
            "Addresses"). Names have to start from letter and can consist of
            only letters, digits and underscore symbol.

        table
            Optional table name for 'list' type placeholder. If not defined
            it would be created from class name (something like
            'osCustomer_Address' for 'Customer::Address' class).

        type
            Placeholder type, one of 'text', 'words', 'integer', 'unsigned',
            'real' or 'list'.

        unique
            If set to non-zero value then this property will have to be
            filled with values that are unique troughout the entire class.
            Placeholder with that modifier can only be added when there are
            no objects of that class in the database.

        An example of adding new single-value property placeholder:

         $customer->add_placeholder(name      => 'middle_name',
                                    type      => 'text',
                                    maxlength => 10);

         $customer->put(middlename => 'Jr.');

        An example of adding new list of properties placeholder:

         $customer->add_placeholder(name  => 'Addresses',
                                    class => 'Customer::Address',
                                    key   => 'address_id');

         my $adlist=$customer->get('Addresses');

         $adlist->put('addr001' => $address);

        NOTE: A placeholder added to an object in fact adds it to all
        objects of the same class regardless of their status - attached or
        detached.

    build_structure (%)
        Convenience method that checks object structure and adds specified
        placeholders if they do not currently exist.

        Upon return object will have at least the given fields. It can have
        some extra fields that were on the object before, but given fields
        guaranteed to exist and have the same descriptions as provided.

        If any existing field has different description than supplied
        build_structure() method will throw an error.

        Example:

         $customer->build_structure(
             Orders => {
                 type => 'list',
                 class => 'Data::Order',
                 key => 'order_id',
                 structure => {
                     total => {
                         type => 'integer',
                         minvalue => 0,
                     },
                 },
             },
             first_name => {
                 type => 'text',
                 maxlength => 100
             },
             last_name => {
                 type => 'text',
                 maxlength => 100
             });

    container_key ()
        If current object is not on top level returns key that refers to the
        current object in the container object that contains current object.

        Would return undef if current object was created with "new" and had
        never been stored anywhere.

    container_object ()
        If current object is not on top level returns container object that
        contains current object. For Global object will return `undef'.

        Will throw an error if current object was created with get_new()
        method or something similar.

        Example:

         my $orders_list=$order->container_object();

    defined ($)
        Checks if there is value for the given property. For list properties
        will always return true even if the list is empty.

        For non existing properties will throw an error.

    delete ($)
        Deletes content of the given property. If you use get() on the
        deleted property you will get empty List for `list' properties or
        `undef' for value properties.

        NOTE: If the name you gave refers to a contained object then
        destroy() method would be called on that object. List object would
        then unlink all its contained object and if that was the only place
        they were linked into then these object would be destroyed too. Be
        careful with delete() method.

        Delete() method would not alter database structure. It can leave
        some tables empty, but it would not change relations scheme.

    describe ($)
        Returns a hash reference that contains description of the given
        field. The format is exactly like you would pass to
        add_placeholder() method.

        Can be used to check limitations and field types. Will return
        `undef' on non-existing fields.

        Example:

         my $description=$customer->describe('first_name');
         print "Type: $description->{type}\n";
         print "Maximum length: $description->{maxlength}\n";

    destroy ()
        Deletes everything inside the current object -- an alias for the
        following code:

         foreach my $key ($customer->keys) {
             $customer->delete($key);
         }

    detach ()
        Detaches current object from its container and from database.
        Detaching an object leads to detaching every object it contains to
        the deepest possible level.

        Once an object is detached it "remembers" a place where it was
        attached and can be re-attached later.

        No changes in the database data would be propagated to the detached
        object and no changes in the detached object would ever change the
        database. An exception is add_placeholder() and drop_placeholder()
        methods that operate on all objects of the same type regardless of
        their status -- detached or attached.

        NOT IMPLEMENTED YET. Almost all supporting infrastructure is in
        place, but currently the only way to get a detached object is to
        call get_new() on List object.

        It is safe to call detach() though. You should do that in places
        where you think this is appropriate. Like that:

         ##
         # Printing all properties. Detach() will load all the values into
         # memory and allow speedy prints. The code will work in exactly the
         # same way with or without detach() but once detach() is implemented
         # there would be speed up.
         #
         my $obj=$customers->get($customer_id);
         $obj->detach();
         foreach my $key ($obj->keys) {
             my $value=$obj->get($key);
             if(ref($value)) {
                 print "obj{$key}=List (" . $value->uri . ")\n";
             }
             else {
                 print "obj{$key}='$value'\n";
             }
         }

    drop_placeholder ($)
        Deletes placeholder and all values stored in the field being deleted
        in all Hash objects. Be careful!

        It might take considerable amount of time to finish if you have
        large database.

        Example:

         $customer->drop_placeholder('Orders');

        There is currently no way to rename a placeholder. You can create
        new one, copy data from the old one to the new one and then drop old
        one.

        If you drop a list placeholder it will effectively chop off entire
        branch that starts at that placeholder and drop all related tables
        in the SQL database.

    exists ($)
        Checks if there is a placeholder for the given key. Here is an
        example:

         if(! $customer->exists('middle_name')) {
             print "No placeholder for 'middle_name' exists in the database\n";
         }

        Not the same as defined() which just checks if given property has
        value or not. Property can have placeholder and still be undefined.

    fetch ($)
        Takes URI style path and returns an object or property referenced by
        that path. If path starts with slash (/) then it goes from the top,
        otherwise - from the current object. Counting objects from top would
        always give you connected object or undef.

        Examples:

         my $zip001=$customer->fetch('Addresses/addr001/zipcode');

         my $customers=$address->fetch('/Customers');

        Currently is only implemented on Glue, relative URI are not
        supported.

    fill (%)
        Takes a hash or another object of the same type and merges all the
        data from it into the current object.

        NOT IMPLEMENTED.

    get ($)
        Retrieves data field or a list reference from the object.

        Example:

         my $addresses_list=$customer->get('Addresses');

         my $first_name=$customer->get('first_name');

        As a convenience (and an optimisation, because database driver would
        be able to optimise that into just one query into database in most
        cases) you can pass more then one property name into the get()
        method. In that case it will return you an array of values in the
        same order that you passed property names.

         my ($name,$phone,$fax)=$customer->get('name','phone','fax');

    is_attached ()
        Boolean method that returns true if the current object is attached
        or false otherwise.

    keys ()
        Returns list of field names and list names stored in that object.
        Excludes connectors and unique_id.

        Example:

         foreach my $key ($object->keys) {
            my $value=$object->get($key);
            print "object.$key=$value\n";
         }

    new (%)
        Creates new instance of a Hash object. Would not work if called
        directly, XAO::Objects' new() method should always be used instead.

        Example:

         my $obj=XAO::Objects->new(objname => 'Data::Customer',
                                   glue => $glue);

        One required argument is 'glue', it must contain a reference to the
        XAO::DO::FS::Glue manpage object.

        As a convenience it is recommended to call get_new() method on the
        list object to get new empty detached objects of the class that list
        can store. If you do so first you will not forget to pass `glue' as
        get_new() will do that for you and second if later on the name of
        the class will change you will not have to worry about that.

        Example:

         my $customer=$customers_list->get_new();

    objtype ()
        For all objects based on Hash returns 'Hash' string.

    put ($$)
        Stores new value into the Hash object. Values can currently only be
        strings and numbers, you cannot store a list.

        On attached objects your changes go directly into the database. On
        detached objects changes accumulate in memory and only get stored
        into the database when you put() that object into an attached list.

        Example:

         $customer->put(full_name => 'John Silver');

        Name must correspond to a previously defined placeholder otherwise
        an error will be thrown.

        Value must meet constrains set for the placeholder, otherwise error
        will be thrown and no changes will be made.

    reattach ()
        The same as to call put() method on upper level container. Works
        only for detached objects and does nothing if the object is already
        attached.

        Note: entire content of an object currently stored in the database
        would be replaced with current object recursively. Be careful!

        All attached objects that refer to the same piece of data would
        immediately start returning updated values on calls to get() method.

        Not implemented yet. Call put() on the list instead to attach the
        object.

    upper_class (;$)
        Returns class name for the hash that contained the list that
        contained current hash object.

    values ()
        Returns a list of all property values for the current object
        including its contained Lists if any.

        Note: the order of values is the same as the order of keys returned
        by keys() method. At least until you modify the object directly on
        indirectly. It is not recommended to use values() method for the
        reason of pure predictability.

    uri ($)
        Returns complete URI to either the object itself (if no argument is
        given) or to a property with the given name.

        That URI can then be used to retrieve a property or object using
        $odb->fetch($uri). Be aware, that fetch() is a relatively slow
        method and should not be abused.

        Example:

         my $uri=$customer->uri;
         print "URI of that customer is: $uri\n";

AUTHORS
    Xao, Inc. (c) 2001. This module was developed by Andrew Maltsev
    <am@xao.com> with the help and valuable comments from other team
    members.

SEE ALSO
    Further reading: the XAO::OS manpage, the XAO::DO::FS::List manpage (aka
    FS::List), the XAO::DO::FS::Glue manpage (aka FS::Glue).

