OME::Session - a user's login session with OME
use OME::SessionManager;
use OME::Session;
# To login to OME:
my $manager = OME::SessionManager->new();
my $session = $manager->createSession($username,$password);
# To obtain the session object after login:
my $session = OME::Session->instance();
my $factory = $session->Factory();
my $config = $session->Configuration();
# Create and edit several DBObject's via the factory
$session->commitTransaction();
# Create and edit several DBObject's via the factory, but make
# a mistake halfway through
$session->rollbackTransaction();
All interaction with OME is done in the context of a session object. This session object encodes the user credentials that were used to login to the OME system, and encapsulates the Factory object which is used for all OME database access.
Within the context of a single Perl process, the Session object is a
singleton. There will only ever be one session for a given
process, fork or thread. All of the OME Perl code is written around
this assumption. The instance method should be used to obtain the
singleton Session instance.
Each session has a session key (a string token) which can be used to refer to a sesson outside the context of the Perl interpreter which created it. This allows a user's session to be represented externally in a file, or in a separate client machine/process. Session objects in Perl can be created either with a username/password pair, or with a session key. The first case causes a new logical session (with a new session key) to be created, while the second allows an existing logical session to persist across Perl processes. The session key is short lived, and must be periodically refreshed.
There is no public constructor for this class. The OME::SessionManager class should be used to create Session objects.
The following methods are available.
my $factory = $session->Factory();
Returns the session's OME::Factory object.
my $config = $session->Configuration();
Returns the session's OME::Configuration object.
my $key = $session->SessionKey();
Returns the session's SessionKey - a string token that can be used to
recover the session object (using
OME::SessionManager) for a short period of
time.
my $user = $session->User();
Returns the Experimenter whose username and password were used to log in.
my $dataset = $session->dataset();
Returns the session's OME::Dataset object.
my $project = $session->project();
Returns the session's OME::Project object.
my $session = OME::Session->bootstrapInstance();
This method is intended for internal use only. It is used to obtain a valid Session object which is not keyed to an OME user. This kind of session is used by the OME installation code to set up the core OME database schema before the first user is created.
A Session created via this method only has valid values for the Factory accessor. It cannot persist across Perl processes, and has no SessionKey. It also does not have a UserState object, and therefore no User, project, dataset, or Configuration.
When the bootstrap session is no longer needed, it can be destroyed with the finishBootstrap method. Usually this is followed immediately by logging in via the standard OME::SessionManager methods.
$session->finishBootstrap();
Destroys a bootstrap session created with the bootstrapInstance
constructor.
my $session = OME::Session->instance();
# Internal use only:
my $session = OME::Session->instance($user_state);
This is the main method those most Perl code will use. The SessionManager methods are only needed for the code specifically related to logging into OME. Code which needs access to the session object after login has completed uses this method instead.
When called with no parameters, this method returns the singleton OME::Session instance. If the user has not logged in yet, an error occurs.
Internally, this method is also used by the OME::SessionManager methods to create a new session object upon login. When called with a single parameter (which should be an instance of OME::UserState), a new session object is created. If a singleton instance already exists, it is destroyed and then salvaged with the new user credentials; otherwise, a new instance is created and initialized with those credentials. The SessionManager is the only class which should ever call the single-parameter version of this method.
OME::Session->idle();
# or
$session->idle();
Explicitly frees resources used since getting the session. After this call, the session will not work properly until revived with createSession. The freed resources include open database transactions, DBObject caches, and temporary files. This method should be called when a persistant process (e.g. an apache child) completes a request. Command line processes don't need to call this method because they typically exit after completing a request.
Explicitly deletes the singleton instance from the process. This should only be used when a true recycle of the Session object (either Configuration or UserState is updated) is needed. You will incur a STDERR warning when using this method.
This method is only intended for multi-threaded code involving the
fork() call. In this case, the child will have a lingering copy of
the session used by the parent thread. The child needs to call this
method immediately after the fork, so that the child process will not
try to clean up the parent's session. (Otherwise, the parent will
eventually die with when it tries to access the database connection
which was closed by the child.) If the child needs its own database
connection, it should use the SessionManager reauthenticate (via
username/password or session key) and create a new Session object.
This method is used to check if an OME::Session has an instance because it is an error to request an instance when one is not defined.
$session->commitTransaction();
Commits the current database transaction.
$session->rollbackTransaction();
Rolls back the current database transaction. Note that this does not invalidate any Perl database objects; callers must be careful to not use any DBObjects that were created or modified during the aborted transaction.
my $filename = $session->getTemporaryFilename($progName,$extension);
Returns an absolute path to a temporary file. The $progName and
$extension parameters are purely informational, and are used to form
the filename. The filename can be used in a standard Perl open
call to create the temporary file. When the temporary file is no
longer needed, it should be closed, and the finishTemporaryFile method
should be called.
Any temporary files which are created but not finished will be cleaned up when the current session finishes, but this behavior should not be relied upon. Please clean up after yourself.
my $path = $session->getScratchDir($progName, $extension);
Returns an absolute path to a temporary directory within OME's temp
directory. A filename is first created by calling the
getTemporaryFilename method. Once a filename is returned, it is
passed to the Perl mkdir function to create a temporary directory.
As with <getTemporaryFilename>, once the directory is no longer
needed, the finishTemporaryFile method should be called.
$session->finishTemporaryFile($filename);
Removes a temporary file or directory created by the
getTemporaryFilename or getScratchDir method. Please, please,
please call this method immediately when you're done with a temporary
file. Do not rely on the automatic session cleanup to remove your
garbage.
This method successfully handles removing the file whether $filename refers to a simple file or to a directory. If it refers to a directory, it and all of its contents are removed, assuming that the Perl process has write access to everything.
my $isGuestSession = $session->isGuestSession
my $isGuestSession = $session->isSuSession
returns true if this is a super-user session
Douglas Creager <dcreager@alum.mit.edu>, Open Microscopy Environment, MIT