GEAS::Connection
================

General Notes:
--------------
The Connection object provides searching, transaction management, and allows
creation of new objects.

(Note: transactions are not yet implemented.)

Once transactions have been implemented, data operations (creation,
deletion, reading and writing data) that require a transaction will throw a
TransactionNotInProgress exception.


Parents:
--------
TransactionFactory


Attributes:
-----------

Name       : currentUserID
Type       : string (readonly)
Description: Not fully implemented, or needed yet.

Name       : classes
Type       : classnames (readonly) [array of strings]
Description: This attribute contains an array of all business classes
             accessible to the user.

Name       : schema
Type       : classlist (readonly) [array of ClassDefinition structures]
Description: Not implemented


Methods:
--------

Name:
    newQuery

Synopsis:
    Query newQuery()

Description:
    A Query object contains information for more flexible queries of the
database. This function creates a new query with no data values set.

Arguments:
    None

Result:
    A valid Query instance.

Exceptions:
    None

Example:

See Also:


Name:
    executeQuery

Synopsis:
    ObjectList executeQuery( in Query::Query querytoperform )

Description:
    This method will execute the query defined by a Query object, and then
return an ObjectList instance that contains the results of the query.

Arguments:
    querytoperform : A completed Query object containing the full details of
                     the query

Result:
    An ObjectList instance containing the results of the query. (It will have
    no entries if no objects were found.)

Exceptions:
    None

Example:

See Also:


Name:
    getClassDefinition

Synopsis:
    ClassDefinition getClassDefinition( in string name )

Description:
    Get a list of all fields defined by a specific class, excluding any
inherited fields, and a list of all parent classes, if any.

Arguments:
    name : The name of the class to examine

Result:
    A ClassDefinition instance describing the class.

Exceptions:
    UnknownClass : The requested class does not exist
    ServerError  : Some other error

Example:

See Also:


Name:
    getFullClassDefinition

Synopsis:
    ClassDefinition getFullClassDefinition( in string name )

Description:
    Get a list of all fields defined by a specific class, including all
inherited fields, and a list of the names of all parent classes. Note that
each field definition structure identifies which specific class provided
that field.

Arguments:
    name : The name of the class to examine

Result:
    A ClassDefinition instance defining the class.

Exceptions:
    UnknownClass : The requested class does not exist
    ServerError  : Some other error

Example:
See Also:


Name:
    getLookupFieldOptions

Synopsis:
    LookupOptions getLookupFieldOptions( in string classname ,
                                         in string fieldname )

Description:
    Get a list of all possible options for a particular lookup field in a
particular class.

Arguments:
    classname : The name of the field to examine
    fieldname : The name of the field in that class

Result:
    An array of LookupOption instances

Exceptions:
    UnknownClass   : The requested class does not exist
    UnknownField   : The requested field is not defined in that class
    NotLookupField : The field is of another type
    NotReadable    : An unreadable field was accessed

Example:
See Also:
    doc/usage/lookups.txt


Name:
    supportsFeature

Synopsis:
    boolean supportsFeature( in Feature featureID )

Description:
    Not particularly useful, after all. Don't use it.

Arguments:
Result:
Exceptions:
    None
Example:
See Also:


Name:
    newObject

Synopsis:
    DataObject newObject( in string classname )

Description:
    Create a new instance of a particular class. Any fields with default
values will be set, and all other fields will be left blank.

Arguments:
    classname : The name of the class to instantiate

Result:
    A reference to a new DataObject instance.

Exceptions:
    UnknownClass             : The class was not found
    TransactionNotInProgress : A transaction is required for this operation
    ServerError              : Any other error

Example:
See Also:


Name:
    newEmptyList

Synopsis:
    ObjectList newEmptyList( in string classname )
    
Description:
    This creates a new ObjectList instance that can contain instances of a
particular class (including all classes derived from that class). The list
will be empty initially.

Arguments:
    classname : The name of the class that can be stored in this list

Result:
    A reference to an empty ObjectList instance.

Exceptions:
    UnknownClass             : The class was not found
    TransactionNotInProgress : A transaction is required for this operation
    ServerError              : Any other error

Example:
See Also:


Name:
    loadObjects

Synopsis:
    ObjectList loadObjects( in string classname , in string fieldname ,
                            in string searchvalue )

Description:
    Load a set of objects of a particular class where a particular field is
an exact match for a particular value.

Arguments:
    classname   : The class to load
    fieldname   : The field to use in the search
    searchvalue : Only return objects where the field has this value

Result:
    An ObjectList containing 0 or more instances of the class.

Exceptions:
    TransactionNotInProgress : A transaction is required for this operation
    UnknownClass             : The class was not found
    ServerError              : Any other error
    UnknownField             : The field is not defined in that class

Example:
See Also:


Name:
    loadAll

Synopsis:
    ObjectList loadAll    ( in string classname )

Description:
    Load all instances of a particular class. (Note: if there is a large
number of objects, this method may take a significant amount of time.)

Arguments:
    classname : Load instances of this class

Result:
Exceptions:
    TransactionNotInProgress : A transaction is required for this operation
    UnknownClass             : The class was not found
    ServerError              : Any other error

Example:
See Also:


Name:
    loadSingleObject

Synopsis:
    DataObject loadSingleObject( in string classname , in string fieldname ,
                                 in string searchvalue )

Description:
    Load a single instance of a class, where a field has a particular value.
Note that if multiple objects match the search, an arbitrary instance will
be returned, and this may or may not be consistent over multiple calls to
this method. (The field listed should be a guaranteed unique field.)

Arguments:
    classname   : The class to load
    fieldname   : The field to use in the search
    searchvalue : Only return an object where the field has this value

Result:
    A reference to a DataObject, which may be the CORBA NIL object
reference, if no object was found.

Exceptions:
    TransactionNotInProgress : A transaction is required for this operation
    UnknownClass             : The class was not found
    ServerError              : Any other error
    UnknownField             : The field is not defined in that class

Example:
See Also:


Name:
    flush

Synopsis:
    void flush();

Description:
    This method is no longer required.

Arguments:
Result:
Exceptions:
    None

Example:
See Also:


Name:
    logout

Synopsis:
    void logout();

Description:
    Currently this method does nothing.

Arguments:
Result:
Exceptions:
    None

Example:
See Also:



Name:
    getReferenceDefinition

Synopsis:
    LoadDefinition getReferenceDefinition( in string classname ,
                                           in string fieldname )
Description:
    This method returns the rules used for locating the contents of a
reference, list, or lookup field.

Arguments:
    classname :The classname to examine
    fieldname : The field in that class

Result:
    A 'LoadDefinition' instance, that describes exactly how to locate the
contents of the specified field.

Exceptions:
    None

Example:
See Also:

