Wallet::Object::Base - Generic parent class for wallet objects
package Wallet::Object::Simple;
@ISA = qw(Wallet::Object::Base);
sub get {
my ($self, $user, $host, $time) = @_;
$self->log_action ('get', $user, $host, $time) or return;
return "Some secure data";
}
Wallet::Object::Base is the generic parent class for wallet
objects (data types that can be stored in the wallet system). It provides
default 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.
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).
- new(TYPE, NAME,
DBH)
- Creates a new object with the given object type and name, based on data
already in the database. This method will only succeed if an object of the
given TYPE and NAME is already present in the wallet database. If no such
object exits, throws an exception. 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 Wallet::Schema object, which is stored in the object
and used for any further operations.
- create(TYPE,
NAME, DBH, PRINCIPAL, HOSTNAME [, DATETIME])
- Similar to new() but instead creates a new entry in the database.
This method will throw an exception if an entry for that type and name
already exists in the database or if creating the database record fails.
Otherwise, a new database entry will be created with that type and name,
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().
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().
If the locked flag is set on an object, no actions may be
performed on that object except for the flag methods and show(). All
other actions will be rejected with an error saying the object is
locked.
- acl(TYPE [, ACL,
PRINCIPAL, HOSTNAME [, DATETIME]])
- Sets or retrieves a given object ACL as a numeric ACL ID. TYPE must be one
of "get",
"store",
"show",
"destroy", or
"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 and return true on success and 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.
- 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 the empty
list. To distinguish between an error and an empty return, call
error() afterward. It is guaranteed to return undef unless there
was an error.
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.
- attr_show()
- Returns a formatted text description of the type-specific attributes of
the object, or undef on error. The default implementation of this method
always returns the empty string. If there are any type-specific attributes
set, this method should return that metadata, formatted as key: value
pairs with the keys right-aligned in the first 15 characters, followed by
a space, a colon, and the value.
- Sets or retrieves the comment associated with an object. If no arguments
are given, returns the current comment or undef if no comment is set. If
arguments are given, change the comment to COMMENT and return true on
success and false on failure. Pass in the empty string for COMMENT to
clear the comment.
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.
- destroy(PRINCIPAL,
HOSTNAME [, DATETIME])
- Destroys the object by removing all record of it from the database. The
Wallet::Object::Base 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.
- error([ERROR
...])
- Returns the error of 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.
For the convenience of child classes, this method can also be
called with one or more error strings. If so, those strings are
concatenated together, trailing newlines are removed, any text of the
form
" at \S+ line \d+\.?"
at the end of the message is stripped off, and the result is stored as
the error. Only child classes should call this method with an error
string.
- 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 and return true on
success and false on failure. EXPIRES must be in the format
"YYYY-MM-DD HH:MM:SS", although the time
portion may be omitted. Pass in the empty string for EXPIRES to clear the
expiration date.
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.
- flag_check(FLAG)
- Check whether the given flag is set on an object. Returns true if set,
0 if not set, and undef on error.
- flag_clear(FLAG,
PRINCIPAL, HOSTNAME [, DATETIME])
- Clears FLAG on an object. Returns true on success and false on failure.
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.
- flag_list()
- List the flags set on an object. If no flags are set, returns the empty
list. On failure, returns an empty list. To distinguish between the empty
response and an error, the caller should call error() after an
empty return. It is guaranteed to return undef if there was no error.
- flag_set(FLAG,
PRINCIPAL, HOSTNAME [, DATETIME])
- Sets FLAG on an object. Returns true on success and false on failure. 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.
- 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::Base
implementation just throws an exception.
- history()
- Returns the formatted history for the object. There will be two lines for
each action on the object. The first line has the timestamp of the action
and the action, and the second line gives the user who performed the
action and the host from which they performed it (based on the trace
information passed into the other object methods).
- name()
- Returns the object's name.
- 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 and return true on
success and false on failure. Pass in the empty string for OWNER to clear
the 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.
- show()
- Returns a formatted text description of the object suitable for human
display, or undef on error. 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. The
attr_show() method of the object is also called and any formatted
output it returns will be included. If any ACLs or an owner are set, after
this data there is a blank line and then the information for each unique
ACL, separated by blank lines.
- 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.
- type()
- Returns the object's type.
The following instance methods should not be called externally but
are provided for subclasses to call to implement some generic actions.
- log_action
(ACTION, PRINCIPAL, HOSTNAME, DATETIME)
- Updates the history tables and trace information appropriately for ACTION,
which should be either "get" or
"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.
- 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 "owner",
"acl_get",
"acl_store",
"acl_show",
"acl_destroy",
"acl_flags",
"expires",
"flags", or a value starting with
"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.
wallet-backend(8)
This module is part of the wallet system. The current version is
available from <https://www.eyrie.org/~eagle/software/wallet/>.
Russ Allbery <eagle@eyrie.org>