view release on metacpan or  search on metacpan

Ace.pm  view on Meta::CPAN

classes.

=head1 CREATING NEW DATABASE CONNECTIONS

=head2 connect() -- multiple argument form

    # remote database
    $db = Ace->connect(-host  =>  'beta.crbm.cnrs-mop.fr',
                       -port  =>  20000100);

    # local (non-server) database
    $db = Ace->connect(-path  =>  '/usr/local/acedb);

Use Ace::connect() to establish a connection to a networked or local
AceDB database.  To establish a connection to an AceDB server, use the
B<-host> and/or B<-port> arguments.  For a local server, use the
B<-port> argument.  The database must be up and running on the
indicated host and port prior to connecting to an AceDB server.  The
full syntax is as follows:

    $db = Ace->connect(-host  =>  $host,
                       -port  =>  $port,
		       -path  =>  $database_path,
		       -program     => $local_connection_program
                       -classmapper =>  $object_class,
		       -timeout     => $timeout,
		       -query_timeout => $query_timeout
		       -cache        => {cache parameters},
		      );

The connect() method uses a named argument calling style, and
recognizes the following arguments:

=over 4

=item B<-host>, B<-port>

These arguments point to the host and port of an AceDB server.
AcePerl will use its internal compiled code to establish a connection
to the server unless explicitly overridden with the B<-program>
argument.

=item B<-path>

This argument indicates the path of an AceDB directory on the local
system.  It should point to the directory that contains the I<wspec>
subdirectory.  User name interpolations (~acedb) are OK.

=item B<-user>

Name of user to log in as (when using socket server B<only>).  If not
provided, will attempt an anonymous login.

=item B<-pass>

Password to log in with (when using socket server).

=item B<-url>

An Acedb URL that combines the server type, host, port, user and
password in a single string.  See the connect() method's "single
argument form" description.

=item B<-cache>

AcePerl can use the Cache::SizeAwareFileCache module to cache objects
to disk. This can result in dramatically increased performance in
environments such as web servers in which the same Acedb objects are
frequently reused.  To activate this mechanism, the
Cache::SizeAwareFileCache module must be installed, and you must pass
the -cache argument during the connect() call.

The value of -cache is a hash reference containing the arguments to be
passed to Cache::SizeAwareFileCache.  For example:

   -cache => {
              cache_root         => '/usr/tmp/acedb',
              cache_depth        => 4,
              default_expires_in => '1 hour'
              }

If not otherwise specified, the following cache parameters are assumed:

       Parameter               Default Value
       ---------               -------------
       namespace               Server URL (e.g. sace://localhost:2005)
       cache_root              /tmp/FileCache (dependent on system temp directory)
       default_expires_in      1 day
       auto_purge_interval     12 hours

By default, the cache is not size limited (the "max_size" property is
set to $NO_MAX_SIZE).  To adjust the size you may consider calling the
Ace object's cache() method to retrieve the physical cache and then
calling the cache object's limit_size($max_size) method from time to
time.  See L<Cache::SizeAwareFileCache> for more details.

=item B<-program>

By default AcePerl will use its internal compiled code calls to
establish a connection to Ace servers, and will launch a I<tace>
subprocess to communicate with local Ace databases.  The B<-program>
argument allows you to customize this behavior by forcing AcePerl to
use a local program to communicate with the database.  This argument
should point to an executable on your system.  You may use either a
complete path or a bare command name, in which case the PATH
environment variable will be consulted.  For example, you could force
AcePerl to use the I<aceclient> program to connect to the remote host
by connecting this way:

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

=item B<-classmapper>

The optional B<-classmapper> argument (alias B<-class>) points to the
class you would like to return from database queries.  It is provided
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: