Add the error() method and allow the date argument for tracing to various

method calls to be omitted.  Add full documentation.  This should be
basically functionally complete for the first pass, although there is as
yet no flags implementation.

1 files changed, 196 insertions, 1 deletions

diff --git a/perl/Wallet/Object.pm b/perl/Wallet/Object.pm
index 0cc7d69..602b426 100644
--- a/perl/Wallet/Object.pm
+++ b/perl/Wallet/Object.pm
@@ -79,9 +79,15 @@ sub create {
 }
 
 ##############################################################################
-# History functions
+# Utility functions
 ##############################################################################
 
+# Returns the current error message of the object, if any.
+sub error {
+    my ($self) = @_;
+    return $self->{error};
+}
+
 # Record a global object action for this object.  Takes the action (which must
 # be one of get or store), and the trace information: user, host, and time.
 # Returns true on success and false on failure, setting error appropriately.
@@ -161,6 +167,7 @@ sub log_set {
 # Returns undef on failure and the new value on success.
 sub _set_internal {
     my ($self, $attr, $value, $user, $host, $time) = @_;
+    $time ||= time;
     my $name = $self->{name};
     my $type = $self->{type};
     eval {
@@ -307,6 +314,7 @@ sub show {
 # is stored about this object.
 sub destroy {
     my ($self, $user, $host, $time) = @_;
+    $time ||= time;
     my $name = $self->{name};
     my $type = $self->{type};
     eval {
@@ -327,3 +335,190 @@ sub destroy {
     }
     return 1;
 }
+
+##############################################################################
+# Documentation
+##############################################################################
+
+=head1 NAME
+
+Wallet::Object - Generic parent class for wallet objects
+
+=head1 SYNOPSIS
+
+    package Wallet::Object::Simple;
+    @ISA = qw(Wallet::Object);
+    sub get {
+        my ($self, $user, $host, $time) = @_;
+        $self->log_action ('get', $user, $host, $time) or return undef;
+        return "Some secure data";
+    }
+
+=head1 DESCRIPTION
+
+Wallet::Object is the generic parent class for wallet objects (data types
+that can be stored in the wallet system).  It provides defualt functions and
+behavior, including handling generic object settings.  All handlers for
+objects stored in the wallet should inherit from it.  It is not used
+directly.
+
+=head1 PUBLIC CLASS METHODS
+
+The following methods are called by the rest of the wallet system and should
+be implemented by all objects stored in the wallet.  They should be called
+with the desired wallet object class as the first argument (generally using
+the Wallet::Object::Type->new syntax).
+
+=over 4
+
+=item new(NAME, TYPE, DBH)
+
+Creates a new object with the given object name and type, based on data
+already in the database.  This method will only succeed if an object of the
+given NAME and TYPE is already present in the wallet database.  If no such
+object exits, returns undef.  Otherwise, returns an object blessed into the
+class used for the new() call (so subclasses can leave this method alone and
+not override it).
+
+Takes a database handle, which is stored in the object and used for any
+further operations.  This database handle is taken over by the wallet system
+and its settings (such as RaiseError and AutoCommit) will be modified by the
+object for its own needs.
+
+=item create(NAME, TYPE, DBH, PRINCIPAL, HOSTNAME [, DATETIME])
+
+Similar to new() but instead creates a new entry in the database.  This
+method will fail (returning undef) if an entry for that name and type
+already exists in the database or if creating the database record fails.
+Otherwise, a new database entry will be created with that name and type, no
+owner, no ACLs, no expiration, no flags, and with created by, from, and on
+set to the PRINCIPAL, HOSTNAME, and DATETIME parameters.  If DATETIME isn't
+given, the current time is used.  The database handle is treated as with
+new().
+
+=back
+
+=head1 PUBLIC INSTANCE METHODS
+
+The following methods may be called on instantiated wallet objects.
+Normally, the only methods that a subclass will need to override are get(),
+store(), show(), and destroy().
+
+=over 4
+
+=item acl(TYPE [, ACL, PRINCIPAL, HOSTNAME [, DATETIME]])
+
+Sets or retrieves a given object ACL as a numeric ACL ID.  TYPE must be one
+of C<get>, C<store>, C<show>, C<destroy>, or C<flags>, corresponding to the
+ACLs kept on an object.  If no other arguments are given, returns the
+current ACL setting as an ACL ID or undef if that ACL isn't set.  If other
+arguments are given, change that ACL to ACL.  The other arguments are used
+for logging and history and should indicate the user and host from which the
+change is made and the time of the change.
+
+=item destroy(PRINCIPAL, HOSTNAME [, DATETIME])
+
+Destroys the object by removing all record of it from the database.  The
+Wallet::Object implementation handles the generic database work, but any
+subclass should override this method to do any deletion of files or entries
+in external databases and any other database entries and then call the
+parent method to handle the generic database cleanup.  Returns true on
+success and false on failure.  The arguments are used for logging and
+history and should indicate the user and host from which the change is made
+and the time of the change.
+
+=item error()
+
+Returns the error message from the last failing operation or undef if no
+operations have failed.  Callers should call this function to get the error
+message after an undef return from any other instance method.
+
+=item expires([EXPIRES, PRINCIPAL, HOSTNAME [, DATETIME]])
+
+Sets or retrieves the expiration date of an object.  If no arguments are
+given, returns the current expiration or undef if no expiration is set.  If
+arguments are given, change the expiration to EXPIRES, which should be in
+seconds since epoch.  The other arguments are used for logging and history
+and should indicate the user and host from which the change is made and the
+time of the change.
+
+=item get(PRINCIPAL, HOSTNAME [, DATETIME])
+
+An object implementation must override this method with one that returns
+either the data of the object or undef on some error, using the provided
+arguments to update history information.  The Wallet::Object implementation
+just throws an exception.
+
+=item owner([OWNER, PRINCIPAL, HOSTNAME [, DATETIME]])
+
+Sets or retrieves the owner of an object as a numeric ACL ID.  If no
+arguments are given, returns the current owner ACL ID or undef if none is
+set.  If arguments are given, change the owner to OWNER.  The other
+arguments are used for logging and history and should indicate the user and
+host from which the change is made and the time of the change.
+
+=item show()
+
+Returns a formatted text description of the object suitable for human
+display, or undef on error.  The default implementation shows all of the
+base metadata about the object, formatted as key: value pairs with the keys
+aligned in the first 15 characters followed by a space, a colon, and the
+value.  Object implementations with additional data to display can rely on
+that format to add additional settings into the formatted output or at the
+end with a matching format.
+
+=item store(DATA, PRINCIPAL, HOSTNAME [, DATETIME])
+
+Store user-supplied data into the given object.  This may not be supported
+by all backends (for instance, backends that automatically generate the data
+will not support this).  The default implementation rejects all store()
+calls with an error message saying that the object is immutable.
+
+=back
+
+=head1 UTILITY METHODS
+
+The following instance methods should not be called externally but are
+provided for subclasses to call to implement some generic actions.
+
+=over 4
+
+=item log_action (ACTION, PRINCIPAL, HOSTNAME, DATETIME)
+
+Updates the history tables and trace information appropriately for ACTION,
+which should be either C<get> or C<store>.  No other changes are made to the
+database, just updates of the history table and trace fields with the
+provided data about who performed the action and when.
+
+This function commits its transaction when complete and therefore should not
+be called inside another transaction.  Normally it's called as a separate
+transaction after the data is successfully stored or retrieved.
+
+=item log_set (FIELD, OLD, NEW, PRINCIPAL, HOSTNAME, DATETIME)
+
+Updates the history tables for the change in a setting value for an object.
+FIELD should be one of C<owner>, C<acl_get>, C<acl_store>, C<acl_show>,
+C<acl_destroy>, C<acl_flags>, C<expires>, C<flags>, or a value starting with
+C<type_data> followed by a space and a type-specific field name.  The last
+form is the most common form used by a subclass.  OLD is the previous value
+of the field or undef if the field was unset, and NEW is the new value of
+the field or undef if the field should be unset.
+
+This function does not commit and does not catch database exceptions.  It
+should normally be called as part of a larger transaction that implements
+the change in the setting.
+
+=back
+
+=head1 SEE ALSO
+
+walletd(8)
+
+This module is part of the wallet system.  The current version is available
+from L<http://www.eyrie.org/~eagle/software/wallet/>.
+
+=head1 AUTHOR
+
+Russ Allbery <rra@stanford.edu>
+
+=cut