diff options
| -rw-r--r-- | docs/design-api | 33 | ||||
| -rw-r--r-- | perl/Wallet/Object/Base.pm | 31 | ||||
| -rwxr-xr-x | perl/t/object.t | 8 |
3 files changed, 67 insertions, 5 deletions
diff --git a/docs/design-api b/docs/design-api index af2ff65..6e483b9 100644 --- a/docs/design-api +++ b/docs/design-api @@ -21,7 +21,29 @@ Object API and most of the methods of that module can be used without change. Below are summaries of the methods that a typical object implementation will need to override. Methods other than create() - should set the error with error() and return undef on failure. + should set the error with error() and return undef on failure unless + otherwise noted. + + attr(ATTRIBUTE [, VALUES, PRINCIPAL, HOSTNAME [, DATETIME]]) + + Sets or retrieves a given object attribute. Attributes are used to + store backend-specific information for a particular object type. The + default implementation rejects all ATTRIBUTEs as unknown, so if your + backend has custom attributes, you will need to override this method. + + If no other arguments besides ATTRIBUTE are given, returns the values + of that attribute, if any, as a list. On error, returns a list + containing one undefined element; (undef), in other words. + + If other arguments are given, sets the given ATTRIBUTE values to + VALUES, which must be a reference to an array (even if only one value + is being set). Pass a reference to an empty array to clear the + attribute values. Returns true on success and false on failure. + + If you override this method, be sure to check the locked flag first + and abort if the object is locked, and be sure to call log_set() (with + a "type_data <attribute>" argument) as part of storing the attribute + in the database to update the history information. create(NAME, TYPE, DBH, PRINCIPAL, HOSTNAME [, DATETIME]) @@ -38,8 +60,9 @@ Object API destroy(PRINCIPAL, HOSTNAME [, DATETIME]) Destroys the given object. Backend implementations should override - this method if they need to destroy the object in an external system. - For example, the keytab backend overrides this method to destroy the + this method if they need to destroy the object in an external system + and then call the parent method to do the database cleanup. For + example, the keytab backend overrides this method to destroy the principal in the Kerberos KDC. Be careful not to require that the object exist in a remote system for destroy() to work, since an administrator will want to destroy an orphaned wallet database entry @@ -81,7 +104,9 @@ Object API supported by all backends (for instance, backends that automatically generate the data will not support this). Backends that don't support storing data can just not implement this method and the default - store() method will return an appropriate error. + store() method will return an appropriate error. Don't forget to call + log_action() after successfully storing the data to update the history + and trace information. Be sure to check the locked flag first and abort if the object is locked without storing any data. diff --git a/perl/Wallet/Object/Base.pm b/perl/Wallet/Object/Base.pm index 10864b7..b366d6e 100644 --- a/perl/Wallet/Object/Base.pm +++ b/perl/Wallet/Object/Base.pm @@ -271,6 +271,19 @@ sub acl { } } +# Get or set an attribute on an object. Takes the name of the attribute and, +# if setting, the values and trace information. The values must be provided +# as a reference to an array, even if there is only one value. +# +# Attributes are used by backends for backend-specific information (such as +# enctypes for a keytab). The default implementation rejects all attribute +# names as unknown. +sub attr { + my ($self, $attr, $values, $user, $host, $time) = @_; + $self->error ("unknown attribute $attr"); + return; +} + # Get or set the expires value of an object. Expects an expiration time in # seconds since epoch. If setting the expiration, trace information must also # be provided. @@ -625,6 +638,24 @@ false on failure. Pass in the empty string for ACL to clear the 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 attr(ATTRIBUTE [, VALUES, PRINCIPAL, HOSTNAME [, DATETIME]]) + +Sets or retrieves a given object attribute. Attributes are used to store +backend-specific information for a particular object type and ATTRIBUTE must +be an attribute type known to the underlying object implementation. The +default implementation of this method rejects all attributes as unknown. + +If no other arguments besides ATTRIBUTE are given, returns the values of +that attribute, if any, as a list. On error, returns a list containing one +undefined element. + +If other arguments are given, sets the given ATTRIBUTE values to VALUES, +which must be a reference to an array (even if only one value is being set). +Pass a reference to an empty array to clear the attribute values. 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. Returns true +on success and false on failure. + =item destroy(PRINCIPAL, HOSTNAME [, DATETIME]) Destroys the object by removing all record of it from the database. The diff --git a/perl/t/object.t b/perl/t/object.t index 73efbb7..a69101e 100755 --- a/perl/t/object.t +++ b/perl/t/object.t @@ -3,7 +3,7 @@ # # t/object.t -- Tests for the basic object implementation. -use Test::More tests => 125; +use Test::More tests => 129; use Wallet::ACL; use Wallet::Config; @@ -150,6 +150,12 @@ if ($object->flag_set ('locked', @trace)) { is ($object->error, '', ' and setting it again works'); } +# Attributes. Very boring. +is ($object->attr ('foo'), undef, 'Retrieving an attribute fails'); +is ($object->error, 'unknown attribute foo', ' with the right error'); +is ($object->attr ('foo', [ 'foo' ], @trace), undef, ' and setting fails'); +is ($object->error, 'unknown attribute foo', ' with the right error'); + # Test stub methods and locked status. is ($object->store ("Some data", @trace), undef, 'Store fails'); is ($object->error, "cannot store keytab:${princ}: object is locked", |