diff options
| -rw-r--r-- | perl/Wallet/Object.pm | 197 |
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 |