view release on metacpan or  search on metacpan

Ace.pm  view on Meta::CPAN

for your use if you subclass Ace::Object.  For example, if you have
created a subclass of Ace::Object called Ace::Object::Graphics, you
can have the database return this subclass by default by connecting
this way:

  $db = Ace->connect(-host => 'beta.crbm.cnrs-mop.fr',
                     -port => 20000100,
	             -class=>'Ace::Object::Graphics');

The value of B<-class> can be a hash reference consisting of AceDB
class names as keys and Perl class names as values.  If a class name
does not exist in the hash, a key named _DEFAULT_ will be looked for.
If that does not exist, then Ace will default to Ace::Object.

The value of B<-class> can also be an object or a classname that
implements a class_for() method.  This method will receive three
arguments containing the AceDB class name, object ID and database
handle.  It should return a string indicating the perl class to
create.

=item B<-timeout>

If no response from the server is received within $timeout seconds,
the call will return an undefined value.  Internally timeout sets an
alarm and temporarily intercepts the ALRM signal.  You should be aware
of this if you use ALRM for your own purposes.

NOTE: this feature is temporarily disabled (as of version 1.40)
because it is generating unpredictable results when used with
Apache/mod_perl.

=item B<-query_timeout>

If any query takes longer than $query_timeout seconds, will return an
undefined value.  This value can only be set at connect time, and cannot
be changed once set.

=back

If arguments are omitted, they will default to the following values:

    -host          localhost
    -port          200005;
    -path          no default
    -program       tace
    -class         Ace::Object
    -timeout       25
    -query_timeout 120

If you prefer to use a more Smalltalk-like message-passing syntax, you
can open a connection this way too:

  $db = connect Ace -host=>'beta.crbm.cnrs-mop.fr',-port=>20000100;

The return value is an Ace handle to use to access the database, or
undef if the connection fails.  If the connection fails, an error
message can be retrieved by calling Ace->error.

You may check the status of a connection at any time with ping().  It
will return a true value if the database is still connected.  Note
that Ace will timeout clients that have been inactive for any length
of time.  Long-running clients should attempt to reestablish their 
connection if ping() returns false.

    $db->ping() || die "not connected";

You may perform low-level calls using the Ace client C API by calling
db().  This fetches an Ace::AceDB object.  See THE LOW LEVEL C API for
details on using this object.
 
    $low_level = $db->db();

=head2 connect() -- single argument form

  $db = Ace->connect('sace://stein.cshl.org:1880')

Ace->connect() also accepts a single argument form using a URL-type
syntax.  The general syntax is:

   protocol://hostname:port/path

The I<:port> and I</path> parts are protocol-dependent as described
above.

Protocols:

=over 4

=item sace://hostname:port

Connect to a socket server at the indicated hostname and port.  Example:

   sace://stein.cshl.org:1880

If not provided, the port defaults to 2005.

=item rpcace://hostname:port

Connect to an RPC server at the indicated hostname and RPC service number.  Example:

  rpcace://stein.cshl.org:400000

If not provided, the port defaults to 200005

=item tace:/path/to/database

Open up the local database at F</path/to/database> using tace.  Example:

  tace:/~acedb/elegans

=item /path/to/database

Same as the previous.

=back

=head2 close() Method

You can explicitly close a database by calling its close() method:

   $db->close();