view release on metacpan or  search on metacpan

Ace.pm  view on Meta::CPAN

  return unless eval {require Cache::SizeAwareFileCache};  # not installed

  (my $namespace = "$self") =~ s!/!_!g;
  my %cache_params = (
		      namespace    => $namespace,
		      %DEFAULT_CACHE_PARAMETERS,
		      %$params,
		     );
  my $cache_obj = Cache::SizeAwareFileCache->new(\%cache_params);
  $self->cache($cache_obj);
}

# class method
sub name2db {
  shift;
  my $name = shift;
  return unless defined $name;
  my $d = $NAME2DB{$name};
  # weaken($NAME2DB{$name} = shift) if @_;
  $NAME2DB{$name} = shift if @_;
  $d;
}

# make a new object using indicated class and name pattern
sub new {
  my $self = shift;
  my ($class,$pattern) = rearrange([['CLASS'],['NAME','PATTERN']],@_);
  croak "You must provide -class and -pattern arguments" 
    unless $class && $pattern;
  # escape % signs in the string
  $pattern = Ace->freeprotect($pattern);
  $pattern =~ s/(?<!\\)%/\\%/g;
  my $r = $self->raw_query("new $class $pattern");
  if (defined($r) and $r=~/write access/im) {  # this keeps changing
    $Ace::Error = "Write access denied";
    return;
  }

  unless ($r =~ /($class)\s+\"([^\"]+)\"$/im) {
    $Ace::Error = $r;
    return;
  }
  $self->fetch($1 => $2);
}

# perform an AQL query
sub aql {
  my $self = shift;
  my $query = shift;
  my $db = $self->db;
  my $r = $self->raw_query("aql -j $query");
  if ($r =~ /(AQL error.*)/) {
    $self->error($1);
    return;
  }
  my @r;
  foreach (split "\n",$r) {
    next if m!^//!;
    next if m!^\0!;
    my ($class,$id) = Ace->split($_);
    my @objects = map { $self->class_for($class,$id)->new(Ace->split($_),$self,1)} split "\t";
    push @r,\@objects;
  }
  return @r;
}

# Return the contents of a keyset.  Pattern matches are allowed, in which case
# the keysets will be merged.
sub keyset {
  my $self = shift;
  my $pattern = shift;
  $self->raw_query (qq{find keyset "$pattern"});
  $self->raw_query (qq{follow});
  return $self->_list;
}


#########################################################
# These functions are for low-level (non OO) access only.
# This is for low-level access only.
sub show {
    my ($self,$class,$pattern,$tag) = @_;
    $Ace::Error = '';
    return unless $self->count($class,$pattern);

    # if we get here, then we've got some data to return.
    my @result;
    my $ts = $self->{'timestamps'} ? '-T' : '';
    $self->{database}->query("show -j $ts $tag");
    my $result = $self->read_object;
    unless ($result =~ /(\d+) object dumped/m) {
	$Ace::Error = 'Unexpected close during show';
	return;
    }
    return grep (!m!^//!,split("\n\n",$result));
}

sub read_object {
    my $self = shift;
    return unless $self->{database};
    my $result;
    while ($self->{database}->status == STATUS_PENDING()) {
      my $data = $self->{database}->read();
#      $data =~ s/\0//g;  # get rid of nulls in the buffer
      $result .= $data if defined $data;
    }
    return $result;
}

# do a query, and return the result immediately
sub raw_query {
  my ($self,$query,$no_alert,$parse) = @_;
  $self->_alert_iterators unless $no_alert;
  $self->{database}->query($query, $parse ? ACE_PARSE : () );
  return $self->read_object;
}

# return the last error
sub error {
  my $class = shift;
  $Ace::Error = shift() if defined($_[0]);

Ace.pm  view on Meta::CPAN

    $sequence = $db->fetch(Sequence => 'D12345');
    $local_db->put($sequence);
    @sequences = $db->fetch(Sequence => 'D*');
    $local_db->put(@sequences);

    # Get errors
    print Ace->error;
    print $db->error;

=head1 DESCRIPTION

AcePerl provides an interface to the ACEDB object-oriented database.
Both read and write access is provided, and ACE objects are returned
as similarly-structured Perl objects.  Multiple databases can be
opened simultaneously.

You will interact with several Perl classes: I<Ace>, I<Ace::Object>,
I<Ace::Iterator>, I<Ace::Model>.  I<Ace> is the database accessor, and
can be used to open both remote Ace databases (running aceserver or
gifaceserver), and local ones.

I<Ace::Object> is the superclass for all objects returned from the
database.  I<Ace> and I<Ace::Object> are linked: if you retrieve an
Ace::Object from a particular database, it will store a reference to
the database and use it to fetch any subobjects contained within it.
You may make changes to the I<Ace::Object> and have those changes
written into the database.  You may also create I<Ace::Object>s from
scratch and store them in the database.

I<Ace::Iterator> is a utility class that acts as a database cursor for
long-running ACEDB queries.  I<Ace::Model> provides object-oriented
access to ACEDB's schema.

Internally, I<Ace> uses the I<Ace::Local> class for access to local
databases and I<Ace::AceDB> for access to remote databases.
Ordinarily you will not need to interact directly with either of these
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:

  $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