arlut.csd.ganymede
Class GanymedeSession

java.lang.Object
  |
  +--java.rmi.server.RemoteObject
        |
        +--java.rmi.server.RemoteServer
              |
              +--java.rmi.server.UnicastRemoteObject
                    |
                    +--arlut.csd.ganymede.GanymedeSession

All Implemented Interfaces:

java.rmi.Remote, java.io.Serializable, Session, java.rmi.server.Unreferenced

public final class GanymedeSession

extends java.rmi.server.UnicastRemoteObject

implements Session, java.rmi.server.Unreferenced

User-level session object in the Ganymede server. Each client that logs in to the Ganymede server through the GanymedeServer login() method gets a GanymedeSession object, which oversees that client's interactions with the server. The client talks to its GanymedeSession object through the Session RMI interface, making calls to access schema information and database objects in the server.

The GanymedeSession class provides query and editing services to the client, tracks the client's status, and manages permissions. Most of the actual database handling is done through a second, database-layer session object called a DBSession that GanymedeSession maintains for each user. GanymedeSession methods like view_db_object() and edit_db_object() make calls on the DBSession to actually access DBObjects in the Ganymede database. The client then receives a serialized ReturnVal which may include a remote db_object reference so that the client can directly talk to the DBObject or DBEditObject over RMI.

Once a GanymedeSession is created by the GanymedeServer's login() method, the client is considered to be authenticated, and may make as many Session calls as it likes, until the GanymedeSession's logout() method is called. If the client dies or loses its network connection to the Ganymede server for more than 10 minutes, the RMI system will automatically call GanymedeSession's unreferenced() method, which will log the client out from the server.

The Ganymede server is transactional, and the client must call openTransaction() before making any changes via edit_db_object() or other editing methods. In turn, changes made by the client using the edit_db_object() and related methods will not actually be 'locked-in' to the Ganymede database until the commitTransaction() method is called.

Most methods in this class are synchronized to avoid race condition security holes between the persona change logic and the actual operations.

See Also:

Serialized Form

Field Summary

(package private) boolean	beforeversupergash GanymedeSessions created for internal operations always operate with supergash privileges.
(package private) arlut.csd.ganymede.Client	client Remote reference to our client
(package private) java.lang.String	clienthost The DNS name for the client's host
(package private) arlut.csd.ganymede.serverClientProxy	clientProxy Async partial proxy for sending messages to the client.
(package private) java.util.Date	connecttime The time that this client initially connected to the server.
(package private) static boolean	debug
(package private) arlut.csd.ganymede.DBObject	defaultObj A reference to the Ganymede DBObject storing our default permissions, or the permissions that applies when we are not in supergash mode and we do not have any ownership over the object in question.
(package private) arlut.csd.ganymede.PermMatrix	defaultPerms This variable stores the permission bits that are applicable to generic objects not specifically owned by this persona.
(package private) arlut.csd.ganymede.PermMatrix	delegatableDefaultPerms This variable stores the permission bits that are applicable to generic objects not specifically owned by this persona and which the current admin has permission to delegate to subordinate roles.
(package private) arlut.csd.ganymede.PermMatrix	delegatablePersonaPerms This variable stores the permission bits that are applicable to objects that the current persona has ownership privilege over and which the current admin has permission to delegate to subordinate roles.
boolean	enableOversight If this variable is set to false, no custom wizard code will ever be invoked, and required fields will not be forced.
boolean	enableWizards This variable tracks whether or not the client desires to have wizards presented.
private arlut.csd.Util.booleanSemaphore	forcingSemaphore A flag to let the forceOff() logic know that another thread has already tried to knock off the user.
(package private) java.util.Date	lastActionTime The time of the user's last top-level operation..
(package private) java.lang.String	lastEvent Description of the last action recorded for this client.
private arlut.csd.Util.booleanSemaphore	loggedInSemaphore If true, the user is currently logged in.
(package private) java.util.Vector	newObjectOwnerInvids This variable is a vector of object references (Invid's) to the owner groups that the client has requested newly created objects be placed in.
(package private) int	objectsCheckedOut A count of how many objects this session has currently checked out.
(package private) arlut.csd.ganymede.DBObjectBase	permBase Convenience persistent reference to the Permission Matrix object base
(package private) static boolean	permsdebug
(package private) java.util.Date	permTimeStamp When did we last update our local cache/summary of permissions records?
(package private) arlut.csd.ganymede.DBObjectBase	personaBase Convenience persistent reference to the adminPersonae object base
(package private) arlut.csd.ganymede.Invid	personaInvid The object reference identifier for the current persona, if any.
(package private) java.lang.String	personaName The name of the current persona, of the form '<username>:<description>', for example, 'broccol:GASH Admin'.
(package private) arlut.csd.ganymede.DBObject	personaObj A reference to our current persona object.
(package private) arlut.csd.ganymede.PermMatrix	personaPerms This variable stores the permission bits that are applicable to objects that the current persona has ownership privilege over.
(package private) java.util.Date	personaTimeStamp When did we last check our persona permissions?
(package private) boolean	remotelyAccessible If true, this GanymedeSession will export its objects and fields for direct access via RMI.
(package private) boolean	semaphoreLocked if this session is on the GanymedeServer's lSemaphore, this boolean will be true.
(package private) arlut.csd.ganymede.DBSession	session Our DBSession object.
(package private) java.lang.String	status The current status message for this client.
(package private) boolean	supergashMode A flag indicating whether the client has supergash priviliges.
(package private) boolean	timedout If true, the user has had a soft timeout and needs to re-authenticate with their password, even for their non-privileged username
(package private) arlut.csd.ganymede.AdminEntry	userInfo This variable caches the AdminEntry object which is reported to admin consoles connected to the server when the console is updated.
(package private) arlut.csd.ganymede.Invid	userInvid The object reference identifier for the logged in user, if any.
(package private) java.lang.String	username The unique name that the user is connected to the server under..
(package private) java.util.Vector	visibilityFilterInvids This variable is a vector of object references (Invid's) to the owner groups that the client has requested the listing of objects be restricted to.
(package private) arlut.csd.ganymede.GanymediatorWizard	wizard A GanymedeSession can have a single wizard active.
(package private) arlut.csd.ganymede.GanymedeXMLSession	xSession If this session is being driven by a GanymedeXMLSession, this reference will be non-null.

Fields inherited from class java.rmi.server.UnicastRemoteObject

Fields inherited from class java.rmi.server.RemoteServer

Fields inherited from class java.rmi.server.RemoteObject

ref

Constructor Summary

GanymedeSession()
Constructor for a server-internal GanymedeSession.

GanymedeSession(arlut.csd.ganymede.Client client, java.lang.String loginName, arlut.csd.ganymede.DBObject userObject, arlut.csd.ganymede.DBObject personaObject, boolean exportObjects)
Constructor used to create a server-side attachment for a Ganymede client.

GanymedeSession(java.lang.String sessionLabel)
Constructor for a server-internal GanymedeSession.

Method Summary

arlut.csd.ganymede.ReturnVal	abortTransaction() This method causes all changes made by the client to be thrown out by the database, and the transaction is closed.
private void	addResultRow(arlut.csd.ganymede.DBObject obj, arlut.csd.ganymede.Query query, arlut.csd.ganymede.QueryResult result, boolean internal, arlut.csd.ganymede.DBEditObject perspectiveObject) This private method takes care of adding an object to a query result, checking permissions and what-not as needed.
void	checkIn() This method is used by the server to decrement the admin console's display of the number of objects this user session has checked out and/or created.
(package private) void	checklogin() This private method is called by all methods in GanymedeSession that require the client to be logged in to operate.
void	checkOut() This method is used by the server to increment the admin console's display of the number of objects this user session has checked out and/or created.
void	checkpoint(java.lang.String key) Pass-through method for schema kit code.
arlut.csd.ganymede.ReturnVal	clone_db_object(arlut.csd.ganymede.Invid invid) Clone a new object from object <invid>.
arlut.csd.ganymede.ReturnVal	commitTransaction() This method causes all changes made by the client to be 'locked in' to the database.
arlut.csd.ganymede.ReturnVal	commitTransaction(boolean abortOnFail) This method causes all changes made by the client to be 'locked in' to the database.
arlut.csd.ganymede.ReturnVal	create_db_object(short type) Create a new object of the given type.
arlut.csd.ganymede.ReturnVal	create_db_object(short type, boolean embedded) Create a new object of the given type.
java.lang.String	describe(arlut.csd.ganymede.Invid invid) This method is intended as a lightweight way of returning a handy description of the type and label of the specified invid.
arlut.csd.ganymede.DumpResult	dump(arlut.csd.ganymede.Query query) This method provides the hook for doing a fast database dump to a string form.
arlut.csd.ganymede.ReturnVal	edit_db_object(arlut.csd.ganymede.Invid invid) Check an object out from the database for editing.
void	enableOversight(boolean val) This method is used to allow local server-side code to request that no oversight be maintained over changes made to the server through this GanymedeSession.
void	enableWizards(boolean val) This method is used to allow a client to request that wizards not be provided in response to actions by the client.
private boolean	filterMatch(arlut.csd.ganymede.DBObject obj) This method returns true if the visibility filter vector allows visibility of the object in question.
arlut.csd.ganymede.ReturnVal	filterQueries(java.util.Vector ownerInvids) This method may be used to cause the server to pre-filter any object listing to only show those objects directly owned by owner groups referenced in the ownerInvids list.
arlut.csd.ganymede.QueryResult	filterQueryResult(arlut.csd.ganymede.QueryResult qr) This method applies this GanymedeSession's current owner filter to the given QueryResult <qr> and returns a QueryResult with any object handles that are not matched by the filter stripped.
arlut.csd.ganymede.Invid	findLabeledObject(java.lang.String name, short type) Returns an Invid for an object of a specified type and name, or null if no such object could be found.
(package private) void	forceOff(java.lang.String reason) If the server decides this person needs to get off (if the user times out, is forced off by an admin, or if the server is going down), it will call this method to knock them off.
arlut.csd.ganymede.AdminEntry	getAdminEntry() This method is used to generate a serializable AdminEntry object summarizing this GanymedeSession's state for the admin console.
arlut.csd.ganymede.BaseListTransport	getBaseList() Returns a serialized representation of the object types defined on the server.
arlut.csd.ganymede.CategoryTransport	getCategoryTree() Returns a serialized representation of the basic category and base structure on the server.
arlut.csd.ganymede.CategoryTransport	getCategoryTree(boolean hideNonEditables) Returns a serialized representation of the basic category and base structure on the server.
java.lang.String	getClientHostName() This method returns the name of the system that the client is connected from.
(package private) arlut.csd.ganymede.DBObject	getContainingObj(arlut.csd.ganymede.DBObject object) This method finds the ultimate owner of an embedded object
arlut.csd.ganymede.ReturnVal	getDataXML(arlut.csd.ganymede.FileReceiver receiver, boolean logOffOnFailure) This method is called by the XML client to initiate a dump of the entire data contents of the server.
java.util.Vector	getFieldTemplateVector(short baseId) Returns a vector of field definition templates, in display order.
java.lang.String	getHelpBase() This method is used to tell the client where to look to access the Ganymede help document tree.
java.lang.StringBuffer	getMessage(java.lang.String key, boolean onlyShowIfNew) This method is used to allow the client to retrieve messages like the motd from the server.
java.lang.StringBuffer	getMessageHTML(java.lang.String key, boolean onlyShowIfNew) This method is used to allow the client to retrieve messages like the motd from the server.
java.lang.String	getMyUserName() This method returns the identification string that the server has assigned to the user.
java.util.Vector	getObjects(short baseid) This is a method to allow code in the server to quickly and safely get a full list of objects in an object base.
arlut.csd.ganymede.QueryResult	getOwnerGroups() This method returns a QueryResult of owner groups that the current persona has access to.
arlut.csd.ganymede.PermEntry	getPerm(arlut.csd.ganymede.DBObject object) This method takes the administrator's current persona, considers the owner groups the administrator is a member of, checks to see if the object is owned by that group, and determines the appropriate permission bits for the object.
arlut.csd.ganymede.PermEntry	getPerm(arlut.csd.ganymede.DBObject object, short fieldId) This method takes the administrator's current persona, considers the owner groups the administrator is a member of, checks to see if the object is owned by that group, and determines the appropriate permission bits for the field in the object.
(package private) arlut.csd.ganymede.PermEntry	getPerm(short baseID, boolean includeOwnedPerms) This method returns the generic permissions for a object type.
(package private) arlut.csd.ganymede.PermEntry	getPerm(short baseID, short fieldID, boolean includeOwnedPerms) This method returns the current persona's default permissions for a base and field.
arlut.csd.ganymede.DBObject	getPersona() This method gives access to the DBObject for the administrator's persona record, if any.
java.util.Vector	getPersonae() This method returns a list of personae names available to the user logged in.
arlut.csd.ganymede.Invid	getPersonaInvid() Convenience method to get access to this session's persona invid.
arlut.csd.ganymede.Category	getRootCategory() Deprecated. Superseded by the more efficient getCategoryTree()
arlut.csd.ganymede.ReturnVal	getSchemaXML(arlut.csd.ganymede.FileReceiver receiver, boolean logOffOnFailure) This method is called by the XML client to initiate a dump of the server's schema definition in XML format.
arlut.csd.ganymede.DBSession	getSession() This method returns a reference to the DBSession object encapsulated by this GanymedeSession object.
java.util.Vector	getTypes() Deprecated. Superseded by the more efficient getBaseList()
(package private) arlut.csd.ganymede.DBObject	getUser() Convenience method to get access to this session's UserBase instance.
arlut.csd.ganymede.Invid	getUserInvid() Convenience method to get access to this session's user invid.
arlut.csd.ganymede.GanymediatorWizard	getWizard() Returns the active wizard, if any, for this GanymedeSession.
arlut.csd.ganymede.ReturnVal	getXMLDump(arlut.csd.ganymede.FileReceiver receiver, boolean logOffOnFailure) This method is called by the XML client to initiate a dump of the server's entire database, schema and data, in XML format.
arlut.csd.ganymede.ReturnVal	inactivate_db_object(arlut.csd.ganymede.Invid invid) Inactivate an object in the database
java.util.Vector	internalQuery(arlut.csd.ganymede.Query query) This method provides the hook for doing all manner of internal object listing for the Ganymede database.
private arlut.csd.ganymede.QueryResult	intersectQueries(arlut.csd.ganymede.Query query, arlut.csd.ganymede.QueryResult temp_result, arlut.csd.ganymede.DBLock rLock) This private method takes care of intersecting the result of a query operation against any linked queries to filter a cluster of queries.
boolean	isLoggedIn()
private boolean	isMemberAll(java.util.Vector owners) This helper method iterates through the owners vector and checks to see if the current personaInvid is a member of all of the groups through either direct membership or through membership of an owning group.
boolean	isSuperGash()
boolean	isWizardActive() Returns true if a wizard is currently interacting with the user.
boolean	isWizardActive(arlut.csd.ganymede.GanymediatorWizard wizard) Returns true if a particular wizard is currently interacting with the user.
void	logout() Log out this session.
void	logout(boolean forced_off) Log out this session.
arlut.csd.ganymede.ReturnVal	openTransaction(java.lang.String describe) This method call initiates a transaction on the server.
arlut.csd.ganymede.ReturnVal	openTransaction(java.lang.String describe, boolean interactive) This method call initiates a transaction on the server.
boolean	personaMatch(arlut.csd.ganymede.DBObject obj) Returns true if the active persona has some sort of owner/access relationship with the object in question through its list of owner groups.
arlut.csd.ganymede.QueryResult	query(arlut.csd.ganymede.Query query) This method provides the hook for doing all manner of simple object listing for the Ganymede database.
arlut.csd.ganymede.QueryResult	query(arlut.csd.ganymede.Query query, arlut.csd.ganymede.DBEditObject perspectiveObject) Server-side method for doing object listing with support for DBObject's lookupLabel method.
arlut.csd.ganymede.QueryResult	queryDispatch(arlut.csd.ganymede.Query query, boolean internal, boolean forTransport, arlut.csd.ganymede.DBLock extantLock, arlut.csd.ganymede.DBEditObject perspectiveObject) This method is the primary Query engine for the Ganymede databases.
arlut.csd.ganymede.QueryResult	queryInvids(java.util.Vector invidVector) This method allows the client to get a status update on a specific list of invids.
arlut.csd.ganymede.ReturnVal	reactivate_db_object(arlut.csd.ganymede.Invid invid) Reactivates an inactivated object in the database
private boolean	recursePersonaMatch(arlut.csd.ganymede.Invid owner, java.util.Vector alreadySeen) Recursive helper method for personaMatch..
private boolean	recursePersonasMatch(java.util.Vector owners, java.util.Vector alreadySeen) Recursive helper method for personaMatch..
boolean	registerWizard(arlut.csd.ganymede.GanymediatorWizard wizard) This method is used to register a wizard for this GanymedeSession.
arlut.csd.ganymede.ReturnVal	remove_db_object(arlut.csd.ganymede.Invid invid) Remove an object from the database
private void	resetDefaultPerms() This convenience method resets defaultPerms from the default permission object in the Ganymede database.
boolean	rollback(java.lang.String key) Pass-through method for schema kit code.
boolean	selectPersona(java.lang.String persona, java.lang.String password) This method is used to select an admin persona, changing the permissions that the user has and the objects that are accessible in the database.
void	sendHTMLMail(java.lang.String address, java.lang.String subject, java.lang.StringBuffer body, java.lang.StringBuffer HTMLbody) This method allows clients to cause mail to be sent from the Ganymede server when they can't do it themselves.
void	sendMail(java.lang.String address, java.lang.String subject, java.lang.StringBuffer body) This method allows clients to cause mail to be sent from the Ganymede server when they can't do it themselves.
(package private) void	sendMessage(int type, java.lang.String message) This method is used to send an asynchronous message to the client.
private arlut.csd.ganymede.ReturnVal	sendXML(arlut.csd.ganymede.FileReceiver receiver, boolean sendData, boolean sendSchema, boolean logOffOnFailure) Private server-side helper method used to transmit the server's database in XML format to an FileReceiver remote receiving interface.
arlut.csd.ganymede.ReturnVal	setDefaultOwner(java.util.Vector ownerInvids) This method may be used to set the owner groups of any objects created hereafter.
(package private) void	setLastError(java.lang.String error) This method used to be used to flag an error condition that the client could then call getLastError() to look up.
private void	setLastEvent(java.lang.String text)
void	setXSession(arlut.csd.ganymede.GanymedeXMLSession xSession)
(package private) void	timeCheck() This method is called by a background thread on the server, and knocks this user off if they are a remote user who has been inactive for a long time.
java.lang.String	toString() This method provides a handy description of this session.
void	unreferenced() This method is called when the Java RMI system detects that this remote object is no longer referenced by any remote objects.
void	unregisterWizard(arlut.csd.ganymede.GanymediatorWizard wizard) Unregisters a wizard from this GanymedeSession.
void	updatePerms(boolean forceUpdate) This non-exported method is used to generate a comprehensive permissions matrix that applies to all objects owned by the active persona for this user.
arlut.csd.ganymede.ReturnVal	view_db_object(arlut.csd.ganymede.Invid invid) View an object from the database.
java.lang.StringBuffer	viewAdminHistory(arlut.csd.ganymede.Invid invid, java.util.Date since) This method returns a multi-line string containing excerpts from the Ganymede log relating to <invid>, since time <since>.
java.lang.StringBuffer	viewObjectHistory(arlut.csd.ganymede.Invid invid, java.util.Date since) This method returns a multi-line string containing excerpts from the Ganymede log relating to <invid>, since time <since>.
java.lang.StringBuffer	viewObjectHistory(arlut.csd.ganymede.Invid invid, java.util.Date since, boolean fullTransactions) This method returns a multi-line string containing excerpts from the Ganymede log relating to <invid>, since time <since>.
java.lang.String	viewObjectLabel(arlut.csd.ganymede.Invid invid) This method is intended as a lightweight way of returning the current label of the specified invid.

Methods inherited from class java.rmi.server.UnicastRemoteObject

clone, exportObject, exportObject, exportObject, unexportObject

Methods inherited from class java.rmi.server.RemoteServer

getClientHost, getLog, setLog

Methods inherited from class java.rmi.server.RemoteObject

equals, getRef, hashCode, toStub

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

debug

static final boolean debug

See Also:

Constant Field Values

permsdebug

static final boolean permsdebug

See Also:

Constant Field Values

client

arlut.csd.ganymede.Client client

Remote reference to our client

clientProxy

arlut.csd.ganymede.serverClientProxy clientProxy

Async partial proxy for sending messages to the client.

semaphoreLocked

boolean semaphoreLocked

if this session is on the GanymedeServer's lSemaphore, this boolean will be true.

loggedInSemaphore

private arlut.csd.Util.booleanSemaphore loggedInSemaphore

If true, the user is currently logged in.

timedout

boolean timedout

If true, the user has had a soft timeout and needs to re-authenticate with their password, even for their non-privileged username

forcingSemaphore

private arlut.csd.Util.booleanSemaphore forcingSemaphore

A flag to let the forceOff() logic know that another thread has already tried to knock off the user.

supergashMode

boolean supergashMode

A flag indicating whether the client has supergash priviliges. We keep track of this to speed internal operations.

beforeversupergash

boolean beforeversupergash

GanymedeSessions created for internal operations always operate with supergash privileges. We'll set this flag to true to avoid having to do persona membership checks on initial set-up.

objectsCheckedOut

int objectsCheckedOut

A count of how many objects this session has currently checked out.

enableWizards

public boolean enableWizards

This variable tracks whether or not the client desires to have wizards presented. If this is false, custom plug-in code for the object types stored in the DBStore may either refuse certain operations or will resort to taking a default action.

enableOversight

public boolean enableOversight

If this variable is set to false, no custom wizard code will ever be invoked, and required fields will not be forced. This is intended primarily for direct database loading.

This variable is not intended ever to be available to the client, but should only be set by local server code.

connecttime

java.util.Date connecttime

The time that this client initially connected to the server. Used by the admin console code.

lastActionTime

java.util.Date lastActionTime

The time of the user's last top-level operation.. Used to provide guidance on time-outs. Updated whenever checklogin() is called.

username

java.lang.String username

The unique name that the user is connected to the server under.. this may be <username>[2], <username>[3], etc., if the user is connected to the server multiple times. The username will be unique on the server at any given time.

username should never be null. If a client logs in directly to a persona, username will be that personaname plus an optional session id.

userInvid

arlut.csd.ganymede.Invid userInvid

The object reference identifier for the logged in user, if any. If the client logged in directly to a persona account, this will be null. See personaInvid in that case.

clienthost

java.lang.String clienthost

The DNS name for the client's host

status

java.lang.String status

The current status message for this client. The GanymedeAdmin code that manages the admin consoles will consult this String when it updates the admin consoles.

lastEvent

java.lang.String lastEvent

Description of the last action recorded for this client. The GanymedeAdmin code that manages the admin consoles will consult this String when it updates the admin consoles.

session

arlut.csd.ganymede.DBSession session

Our DBSession object. DBSession is the generic DBStore access layer. A GanymedeSession is layered on top of a DBSession to provide access control and remote access via RMI. The DBSession object is accessible to server-side code only and provides transaction support.

wizard

arlut.csd.ganymede.GanymediatorWizard wizard

A GanymedeSession can have a single wizard active. If this variable is non-null, a custom type-specific DBEditObject subclass has instantiated a wizard to interact with the user.

personaBase

arlut.csd.ganymede.DBObjectBase personaBase

Convenience persistent reference to the adminPersonae object base

personaTimeStamp

java.util.Date personaTimeStamp

When did we last check our persona permissions?

personaObj

arlut.csd.ganymede.DBObject personaObj

A reference to our current persona object. We save this so we can look up owner groups and what not more quickly. An end-user logged in without any extra privileges will have a null personaObj value.

personaName

java.lang.String personaName

The name of the current persona, of the form '<username>:<description>', for example, 'broccol:GASH Admin'. If the user is logged in with just end-user privileges, personaName will be null.

personaInvid

arlut.csd.ganymede.Invid personaInvid

The object reference identifier for the current persona, if any.

permBase

arlut.csd.ganymede.DBObjectBase permBase

Convenience persistent reference to the Permission Matrix object base

permTimeStamp

java.util.Date permTimeStamp

When did we last update our local cache/summary of permissions records?

personaPerms

arlut.csd.ganymede.PermMatrix personaPerms

This variable stores the permission bits that are applicable to objects that the current persona has ownership privilege over. This matrix is always a permissive superset of defaultPerms.

defaultPerms

arlut.csd.ganymede.PermMatrix defaultPerms

This variable stores the permission bits that are applicable to generic objects not specifically owned by this persona.

Each permission object in the Ganymede database includes permissions as apply to objects owned by the persona and as apply to objects not owned by the persona.

This variable holds the union of the 'as apply to objects not owned by the persona' matrices across all permissions objects that apply to the current persona.

delegatablePersonaPerms

arlut.csd.ganymede.PermMatrix delegatablePersonaPerms

This variable stores the permission bits that are applicable to objects that the current persona has ownership privilege over and which the current admin has permission to delegate to subordinate roles. This matrix is always a permissive superset of delegatableDefaultPerms.

delegatableDefaultPerms

arlut.csd.ganymede.PermMatrix delegatableDefaultPerms

This variable stores the permission bits that are applicable to generic objects not specifically owned by this persona and which the current admin has permission to delegate to subordinate roles.

Each permission object in the Ganymede database includes permissions as apply to objects owned by the persona and as apply to objects not owned by the persona.

This variable holds the union of the 'as apply to objects not owned by the persona' matrices across all permissions objects that apply to the current persona.

defaultObj

arlut.csd.ganymede.DBObject defaultObj

A reference to the Ganymede DBObject storing our default permissions, or the permissions that applies when we are not in supergash mode and we do not have any ownership over the object in question.

newObjectOwnerInvids

java.util.Vector newObjectOwnerInvids

This variable is a vector of object references (Invid's) to the owner groups that the client has requested newly created objects be placed in. While this vector is not-null, any new objects created will be owned by the list of ownergroups held here.

visibilityFilterInvids

java.util.Vector visibilityFilterInvids

This variable is a vector of object references (Invid's) to the owner groups that the client has requested the listing of objects be restricted to. That is, the client has requested that the results of Queries and Dumps only include those objects owned by owner groups in this list. This feature is used primarily for when a client is logged in with supergash privileges, but the user wants to restrict the visibility of objects for convenience.

userInfo

arlut.csd.ganymede.AdminEntry userInfo

This variable caches the AdminEntry object which is reported to admin consoles connected to the server when the console is updated.

remotelyAccessible

boolean remotelyAccessible

If true, this GanymedeSession will export its objects and fields for direct access via RMI.

xSession

arlut.csd.ganymede.GanymedeXMLSession xSession

If this session is being driven by a GanymedeXMLSession, this reference will be non-null.

Constructor Detail

GanymedeSession

public GanymedeSession()
                throws java.rmi.RemoteException

Constructor for a server-internal GanymedeSession. Used when the server's internal code needs to do a query, etc. Note that the Ganymede server will create one of these this fairly early on, and will keep it around for internal usage. Note that we don't add this to the data structures used for the admin console.

Note that all internal session activities (queries, etc.) are currently using a single, synchronized GanymedeSession object.. this mean that only one user at a time can currently be processed for login. 8-(

Internal sessions, as created by this constructor, have full privileges to do any possible operation.

GanymedeSession

public GanymedeSession(java.lang.String sessionLabel)
                throws java.rmi.RemoteException

Constructor for a server-internal GanymedeSession. Used when the server's internal code needs to do a query, etc. Note that the Ganymede server will create one of these this fairly early on, and will keep it around for internal usage. Note that we don't add this to the data structures used for the admin console.

Note that all internal session activities (queries, etc.) are currently using a single, synchronized GanymedeSession object.. this mean that only one user at a time can currently be processed for login. 8-(

Internal sessions, as created by this constructor, have full privileges to do any possible operation.

GanymedeSession

public GanymedeSession(arlut.csd.ganymede.Client client,
                       java.lang.String loginName,
                       arlut.csd.ganymede.DBObject userObject,
                       arlut.csd.ganymede.DBObject personaObject,
                       boolean exportObjects)
                throws java.rmi.RemoteException

Constructor used to create a server-side attachment for a Ganymede client.

This constructor is called by the GanymedeServer login() method.

A Client can log in either as an end-user or as a admin persona. Typically, a client will log in with their end-user name and password, then use selectPersona to gain admin privileges. The server may allow users to login directly with an admin persona (supergash, say), if so configured.

Parameters:

client - Remote object exported by the client, provides id callbacks

userObject - The user record for this login

personaObject - The user's initial admin persona

See Also:

GanymedeServer.login(arlut.csd.ganymede.Client)

Method Detail

setXSession

public void setXSession(arlut.csd.ganymede.GanymedeXMLSession xSession)

isSuperGash

public boolean isSuperGash()

isLoggedIn

public boolean isLoggedIn()

checkpoint

public void checkpoint(java.lang.String key)

Pass-through method for schema kit code. This method is not intended to be available to the client over RMI anymore, as DBSession.checkpoint() now does a thread comparison to make sure that nothing is attempting to do interleaved checkpoint operations, and RMI doesn't guarantee that successive remote method calls from a client will be issued from the same server thread.

rollback

public boolean rollback(java.lang.String key)

Pass-through method for schema kit code. This method is not intended to be available to the client over RMI anymore, as DBSession.checkpoint() now does a thread comparison to make sure that nothing is attempting to do interleaved checkpoint operations, and RMI doesn't guarantee that successive remote method calls from a client will be issued from the same server thread.

checkOut

public void checkOut()

This method is used by the server to increment the admin console's display of the number of objects this user session has checked out and/or created.

checkIn

public void checkIn()

This method is used by the server to decrement the admin console's display of the number of objects this user session has checked out and/or created.

getAdminEntry

public arlut.csd.ganymede.AdminEntry getAdminEntry()

This method is used to generate a serializable AdminEntry object summarizing this GanymedeSession's state for the admin console.

Used by code in GanymedeAdmin.

setLastError

void setLastError(java.lang.String error)

This method used to be used to flag an error condition that the client could then call getLastError() to look up. It has been deprecated from that usage, and now simply logs the error.

timeCheck

void timeCheck()

This method is called by a background thread on the server, and knocks this user off if they are a remote user who has been inactive for a long time.

Note that this method is not synchronized, to avoid nested-monitor deadlock by the timeOutTask between a GanymedeSession object and the GanymedeServer object.

forceOff

void forceOff(java.lang.String reason)

If the server decides this person needs to get off (if the user times out, is forced off by an admin, or if the server is going down), it will call this method to knock them off.

Note that this method is not synchronized, to avoid the possibility of deadlocking the admin console in the case of a deadlocked GanymedeSession.

sendMessage

void sendMessage(int type,
                 java.lang.String message)

This method is used to send an asynchronous message to the client. It is used to update the clients so they know when a build is being processed.

See ClientMessage for the list of acceptable client message types.

unreferenced

public void unreferenced()

This method is called when the Java RMI system detects that this remote object is no longer referenced by any remote objects.

This method handles abnormal logouts and time outs for us. By default, the 1.1 RMI time-out is 10 minutes.

Specified by:

unreferenced in interface java.rmi.server.Unreferenced

See Also:

Unreferenced

logout

public void logout()

Log out this session. After this method is called, no other methods may be called on this session object.

This method is partially synchronized, to avoid locking up the admin console if this user's session has become deadlocked.

Specified by:

logout in interface Session

See Also:

Session

logout

public void logout(boolean forced_off)

Log out this session. After this method is called, no other methods may be called on this session object.

This method is partially synchronized, to avoid locking up the admin console if this user's session has become deadlocked.

enableWizards

public void enableWizards(boolean val)

This method is used to allow a client to request that wizards not be provided in response to actions by the client. This is intended to allow non-interactive or non-gui clients to do work without having to go through a wizard interaction sequence.

Wizards are enabled by default.

Specified by:

enableWizards in interface Session

Parameters:

val - If true, wizards will be enabled.

See Also:

Session

enableOversight

public void enableOversight(boolean val)

This method is used to allow local server-side code to request that no oversight be maintained over changes made to the server through this GanymedeSession.

This is intended only for trusted code that does its own checking and validation on changes made to the database. If oversight is turned off, no wizard code will be called, and the required field logic will be bypassed. Extreme care must be used in disabling oversight, and oversight should only be turned off for direct loading and other situations where there won't be multi-user use, to avoid breaking constraints that custom plug-ins count on.

Oversight is enabled by default.

Parameters:

val - If true, oversight will be enabled.

getHelpBase

public java.lang.String getHelpBase()

This method is used to tell the client where to look to access the Ganymede help document tree.

Specified by:

getHelpBase in interface Session

See Also:

Session

getMessage

public java.lang.StringBuffer getMessage(java.lang.String key,
                                         boolean onlyShowIfNew)

This method is used to allow the client to retrieve messages like the motd from the server. The client can specify that it only wants to see a message if it has changed since the user last logged out. This is intended to support a message of the day type functionality. The server will not necessarily remember the last log out across server restart.

Specified by:

getMessage in interface Session

Parameters:

key - A string, like "motd", indicating what message to retrieve.

onlyShowIfNew - If true, the message will only be returned if it has changed since the user last logged out.

Returns:

A StringBuffer containing the message, if found, or null if no message exists for the key, or if onlyShowIfNew was set and the message was not new.

getMessageHTML

public java.lang.StringBuffer getMessageHTML(java.lang.String key,
                                             boolean onlyShowIfNew)

This method is used to allow the client to retrieve messages like the motd from the server. The client can specify that it only wants to see a message if it has changed since the user last logged out. This is intended to support a message of the day type functionality. The server will not necessarily remember the last log out across server restart.

Specified by:

getMessageHTML in interface Session

Parameters:

key - A string, like "motd", indicating what message to retrieve.

onlyShowIfNew - If true, the message will only be returned if it has changed since the user last logged out.

Returns:

A StringBuffer containing the message, if found, or null if no message exists for the key, or if onlyShowIfNew was set and the message was not new.

getMyUserName

public java.lang.String getMyUserName()

This method returns the identification string that the server has assigned to the user.

Specified by:

getMyUserName in interface Session

See Also:

Session

getClientHostName

public java.lang.String getClientHostName()

This method returns the name of the system that the client is connected from.

toString

public java.lang.String toString()

This method provides a handy description of this session.

Overrides:

toString in class java.rmi.server.RemoteObject

getPersonae

public java.util.Vector getPersonae()

This method returns a list of personae names available to the user logged in.

Specified by:

getPersonae in interface Session

See Also:

Session

selectPersona

public boolean selectPersona(java.lang.String persona,
                             java.lang.String password)

This method is used to select an admin persona, changing the permissions that the user has and the objects that are accessible in the database.

Specified by:

selectPersona in interface Session

See Also:

Session

getOwnerGroups

public arlut.csd.ganymede.QueryResult getOwnerGroups()

This method returns a QueryResult of owner groups that the current persona has access to. This list is the transitive closure of the list of owner groups in the current persona. That is, the list includes all the owner groups in the current persona along with all of the owner groups those owner groups own, and so on.

Specified by:

getOwnerGroups in interface Session

setDefaultOwner

public arlut.csd.ganymede.ReturnVal setDefaultOwner(java.util.Vector ownerInvids)

This method may be used to set the owner groups of any objects created hereafter.

Specified by:

setDefaultOwner in interface Session

Parameters:

ownerInvids - a Vector of Invid objects pointing to ownergroup objects.

filterQueries

public arlut.csd.ganymede.ReturnVal filterQueries(java.util.Vector ownerInvids)

This method may be used to cause the server to pre-filter any object listing to only show those objects directly owned by owner groups referenced in the ownerInvids list. This filtering will not restrict the ability of the client to directly view any object that the client's persona would normally have access to, but will reduce clutter and allow the client to present the world as would be seen by administrator personas with just the listed ownerGroups accessible.

This method cannot be used to grant access to objects that are not accessible by the client's adminPersona.

Calling this method with ownerInvids set to null will turn off the filtering.

Specified by:

filterQueries in interface Session

Parameters:

ownerInvids - a Vector of Invid objects pointing to ownergroup objects.

getTypes

public java.util.Vector getTypes()

Deprecated. Superseded by the more efficient getBaseList()

This method returns a list of remote references to the Ganymede object type definitions. This method will throws a RuntimeException if it is called when the server is in schemaEditMode.

Specified by:

getTypes in interface Session

See Also:

Session

getRootCategory

public arlut.csd.ganymede.Category getRootCategory()

Deprecated. Superseded by the more efficient getCategoryTree()

Returns the root of the category tree on the server

Specified by:

getRootCategory in interface Session

See Also:

Category, Session

getCategoryTree

public arlut.csd.ganymede.CategoryTransport getCategoryTree()

Returns a serialized representation of the basic category and base structure on the server. The returned CategoryTransport will include only object types that are editable by the user.

Specified by:

getCategoryTree in interface Session

See Also:

Category, Session

getCategoryTree

public arlut.csd.ganymede.CategoryTransport getCategoryTree(boolean hideNonEditables)

Returns a serialized representation of the basic category and base structure on the server.

This method is synchronized to avoid any possible deadlock between DBStore and GanymedeSession, as the CategoryTransport constructor calls other synchronized methods on GanymedeSession.

Specified by:

getCategoryTree in interface Session

Parameters:

hideNonEditables - If true, the CategoryTransport returned will only include those object types that are editable by the client.

See Also:

Category, Session

getBaseList

public arlut.csd.ganymede.BaseListTransport getBaseList()

Returns a serialized representation of the object types defined on the server. This BaseListTransport object will not include field information. The client is obliged to call getFieldTemplateVector() on any bases that it needs field information for.

This method is synchronized to avoid any possible deadlock between DBStore and GanymedeSession, as the BaseListTransport constructor calls other synchronized methods on GanymedeSession

Specified by:

getBaseList in interface Session

See Also:

BaseListTransport, Session

getFieldTemplateVector

public java.util.Vector getFieldTemplateVector(short baseId)

Returns a vector of field definition templates, in display order.

This vector may be cached, as it is static for this object type over the lifetime of any GanymedeSession.

Specified by:

getFieldTemplateVector in interface Session

See Also:

FieldTemplate, Session

openTransaction

public arlut.csd.ganymede.ReturnVal openTransaction(java.lang.String describe)

This method call initiates a transaction on the server. This call must be executed before any objects are modified (created, edited, inactivated, removed).

Currently each client can only have one transaction open.. it is an error to call openTransaction() while another transaction is still open, and an error dialog will be returned in that case.

Specified by:

openTransaction in interface Session

Parameters:

describe - An optional string containing a comment to be stored in the modification history for objects modified by this transaction.

See Also:

Session

openTransaction

public arlut.csd.ganymede.ReturnVal openTransaction(java.lang.String describe,
                                                    boolean interactive)

This method call initiates a transaction on the server. This call must be executed before any objects are modified (created, edited, inactivated, removed).

Currently each client can only have one transaction open.. it is an error to call openTransaction() while another transaction is still open, and an error dialog will be returned in that case.

Specified by:

openTransaction in interface Session

Parameters:

describe - An optional string containing a comment to be stored in the modification history for objects modified by this transaction.

See Also:

Session

commitTransaction

public arlut.csd.ganymede.ReturnVal commitTransaction(boolean abortOnFail)

This method causes all changes made by the client to be 'locked in' to the database. When commitTransaction() is called, the changes made by the client during this transaction is logged to a journal file on the server, and the changes will become visible to other clients.

If the transaction cannot be committed for some reason, commitTransaction() will abort the transaction if abortOnFail is true. In any case, commitTransaction() will return a ReturnVal indicating whether or not the transaction could be committed, and whether or not the transaction remains open for further attempts at commit. If ReturnVal.doNormalProcessing is set to true, the transaction remains open and it is up to the client to decide whether to abort the transaction by calling abortTransaction(), or to attempt to fix the reported problem and try another call to commitTransaction().

This method is synchronized to avoid nested-monitor deadlock in DBSession.commitTransaction()

.

Specified by:

commitTransaction in interface Session

Parameters:

abortOnFail - If true, the transaction will be aborted if it could not be committed successfully.

Returns:

a ReturnVal object if the transaction could not be committed, or null if there were no problems. If the transaction was forcibly terminated due to a major error, the doNormalProcessing flag in the returned ReturnVal will be set to false.

See Also:

Session

commitTransaction

public arlut.csd.ganymede.ReturnVal commitTransaction()

This method causes all changes made by the client to be 'locked in' to the database. When commitTransaction() is called, the changes made by the client during this transaction is logged to a journal file on the server, and the changes will become visible to other clients.

commitTransaction() will return a ReturnVal indicating whether or not the transaction could be committed, and whether or not the transaction remains open for further attempts at commit. If ReturnVal.doNormalProcessing is set to true, the transaction remains open and it is up to the client to decide whether to abort the transaction by calling abortTransaction(), or to attempt to fix the reported problem and try another call to commitTransaction().

Specified by:

commitTransaction in interface Session

Returns:

a ReturnVal object if the transaction could not be committed, or null if there were no problems. If the transaction was forcibly terminated due to a major error, the doNormalProcessing flag in the returned ReturnVal will be set to false.

See Also:

Session

abortTransaction

public arlut.csd.ganymede.ReturnVal abortTransaction()

This method causes all changes made by the client to be thrown out by the database, and the transaction is closed.

Specified by:

abortTransaction in interface Session

Returns:

a ReturnVal object if the transaction could not be aborted, or null if there were no problems

See Also:

Session

sendMail

public void sendMail(java.lang.String address,
                     java.lang.String subject,
                     java.lang.StringBuffer body)

This method allows clients to cause mail to be sent from the Ganymede server when they can't do it themselves. The mail will have a From: header indicating the identity of the sender.

body and HTMLbody are StringBuffer's instead of Strings because RMI has a 64k serialization limit on the String class.

Specified by:

sendMail in interface Session

Parameters:

address - The addresses to mail to, may have more than one address separated by commas or spaces.

subject - The subject of this mail, will have 'Ganymede:' prepended by the server.

body - The content of the message.

sendHTMLMail

public void sendHTMLMail(java.lang.String address,
                         java.lang.String subject,
                         java.lang.StringBuffer body,
                         java.lang.StringBuffer HTMLbody)

This method allows clients to cause mail to be sent from the Ganymede server when they can't do it themselves. The mail will have a From: header indicating the identity of the sender.

body and HTMLbody are StringBuffer's instead of Strings because RMI has a 64k serialization limit on the String class.

Specified by:

sendHTMLMail in interface Session

Parameters:

address - The addresses to mail to, may have more than one address separated by commas or spaces.

subject - The subject of this mail, will have 'Ganymede:' prepended by the server.

body - The plain-ASCII content of the message, or null if none.

HTMLbody - The HTML content of the message, or null if none.

queryInvids

public arlut.csd.ganymede.QueryResult queryInvids(java.util.Vector invidVector)

This method allows the client to get a status update on a specific list of invids.

If any of the invids are not currently defined in the server, or if the client doesn't have permission to view any of the invids, those invids' status will not be included in the returned QueryResult.

Specified by:

queryInvids in interface Session

Parameters:

invidVector - Vector of Invid's to get the status for.

See Also:

Session

findLabeledObject

public arlut.csd.ganymede.Invid findLabeledObject(java.lang.String name,
                                                  short type)

Returns an Invid for an object of a specified type and name, or null if no such object could be found.

If the user does not have permission to view the object, null will be returned even if an object by that name does exist.

This method uses the GanymedeSession query() apparatus, and may not be called from a DBEditObject's commitPhase1/2() methods without risking deadlock.

Specified by:

findLabeledObject in interface Session

Parameters:

name - Label for an object

type - Object type id number

dump

public arlut.csd.ganymede.DumpResult dump(arlut.csd.ganymede.Query query)

This method provides the hook for doing a fast database dump to a string form. The DumpResult returned comprises a formatted dump of all visible fields and objects that match the given query.

This method uses the GanymedeSession query() apparatus, and may not be called from a DBEditObject's commitPhase1/2() methods without risking deadlock.

Specified by:

dump in interface Session

See Also:

Query, Session

filterQueryResult

public arlut.csd.ganymede.QueryResult filterQueryResult(arlut.csd.ganymede.QueryResult qr)

This method applies this GanymedeSession's current owner filter to the given QueryResult <qr> and returns a QueryResult with any object handles that are not matched by the filter stripped.

If the submitted QueryResult <qr> is null, filterQueryResult() will itself return null.

query

public arlut.csd.ganymede.QueryResult query(arlut.csd.ganymede.Query query)

This method provides the hook for doing all manner of simple object listing for the Ganymede database.

This method may not be called from a DBEditObject's commitPhase1/2() methods without risking deadlock.

Specified by:

query in interface Session

See Also:

Session

query

public arlut.csd.ganymede.QueryResult query(arlut.csd.ganymede.Query query,
                                            arlut.csd.ganymede.DBEditObject perspectiveObject)

Server-side method for doing object listing with support for DBObject's lookupLabel method.

Parameters:

query - The query to be performed

perspectiveObject - There are occasions when the server will want to do internal querying in which the label of an object matching the query criteria is synthesized for use in a particular context. If non-null, perspectiveObject's lookupLabel method will be used to generate the label for a result entry.

internalQuery

public java.util.Vector internalQuery(arlut.csd.ganymede.Query query)

This method provides the hook for doing all manner of internal object listing for the Ganymede database. This method will not take into account any optional owner filtering, but it will honor the editableOnly flag in the Query.

Returns:

A Vector of Result objects

queryDispatch

public arlut.csd.ganymede.QueryResult queryDispatch(arlut.csd.ganymede.Query query,
                                                    boolean internal,
                                                    boolean forTransport,
                                                    arlut.csd.ganymede.DBLock extantLock,
                                                    arlut.csd.ganymede.DBEditObject perspectiveObject)

This method is the primary Query engine for the Ganymede databases. It is used by dump(), query(), and internalQuery().

Parameters:

query - The query to be handled

internal - If true, the query filter setting will not be honored

forTransport - If true, the QueryResult will build a buffer for serialization

extantLock - If non-null, queryDispatch will not attempt to establish its own lock on the relevant base(s) for the duration of the query. The extantLock must have any bases that the queryDispatch method determines it needs access to locked, or an IllegalArgumentException will be thrown.

perspectiveObject - There are occasions when the server will want to do internal querying in which the label of an object matching the query criteria is synthesized for use in a particular context. If non-null, perspectiveObject's lookupLabel method will be used to generate the label for a result entry.

intersectQueries

private arlut.csd.ganymede.QueryResult intersectQueries(arlut.csd.ganymede.Query query,
                                                        arlut.csd.ganymede.QueryResult temp_result,
                                                        arlut.csd.ganymede.DBLock rLock)

This private method takes care of intersecting the result of a query operation against any linked queries to filter a cluster of queries. This is only of interest when performing a query on both embedded and non-embedded fields of a given object type.

addResultRow

private void addResultRow(arlut.csd.ganymede.DBObject obj,
                          arlut.csd.ganymede.Query query,
                          arlut.csd.ganymede.QueryResult result,
                          boolean internal,
                          arlut.csd.ganymede.DBEditObject perspectiveObject)

This private method takes care of adding an object to a query result, checking permissions and what-not as needed.

This method is not synchronized for performance reasons, but is only to be called from methods synchronized on this GanymedeSession.

Parameters:

obj - The object to add to the query results

query - The query that we are processing, used to get the list of fields we're wanting to return

result - The QueryResult we're building up

internal - If true, we won't check permissions

perspectiveObject - This is an object that can be consulted to see what its lookupLabel() method will return. This can be null without harmful effect, but if is it not null, a custom DBEditObject subclass can choose to present the label of obj from its perspective. This is used to simulate a sort of relational effect for objects linked from the object being added, by letting different fields in the object take on the role of the label when seen from different objects. Yes, it is a big ugly mess.

viewObjectLabel

public java.lang.String viewObjectLabel(arlut.csd.ganymede.Invid invid)

This method is intended as a lightweight way of returning the current label of the specified invid. No locking is done, and the label returned will be viewed through the context of the current transaction, if any.

Specified by:

viewObjectLabel in interface Session

See Also:

Session

describe

public java.lang.String describe(arlut.csd.ganymede.Invid invid)

This method is intended as a lightweight way of returning a handy description of the type and label of the specified invid. No locking is done, and the label returned will be viewed through the context of the current transaction, if any.

viewObjectHistory

public java.lang.StringBuffer viewObjectHistory(arlut.csd.ganymede.Invid invid,
                                                java.util.Date since)

This method returns a multi-line string containing excerpts from the Ganymede log relating to <invid>, since time <since>.

Specified by:

viewObjectHistory in interface Session

Parameters:

invid - The invid identifier for the object whose history is sought

since - Report events since this date, or all events if this is null.

Returns:

A StringBuffer containing a record of events for the Invid in question, or null if permissions are denied to view the history.

See Also:

Session

viewObjectHistory

public java.lang.StringBuffer viewObjectHistory(arlut.csd.ganymede.Invid invid,
                                                java.util.Date since,
                                                boolean fullTransactions)

This method returns a multi-line string containing excerpts from the Ganymede log relating to <invid>, since time <since>.

Specified by:

viewObjectHistory in interface Session

Parameters:

invid - The invid identifier for the object whose history is sought

since - Report events since this date, or all events if this is null.

fullTransactions - If false, only events directly involving the requested object will be included in the result buffer.

Returns:

A StringBuffer containing a record of events for the Invid in question, or null if permissions are denied to view the history.

See Also:

Session

viewAdminHistory

public java.lang.StringBuffer viewAdminHistory(arlut.csd.ganymede.Invid invid,
                                               java.util.Date since)

This method returns a multi-line string containing excerpts from the Ganymede log relating to <invid>, since time <since>.

Specified by:

viewAdminHistory in interface Session

Parameters:

invid - The invid identifier for the admin Persona whose history is sought

since - Report events since this date, or all events if this is null.

Returns:

A String containing a record of events for the Invid in question, or null if permissions are denied to view the history.

See Also:

Session

view_db_object

public arlut.csd.ganymede.ReturnVal view_db_object(arlut.csd.ganymede.Invid invid)

View an object from the database. The ReturnVal returned will carry a db_object reference, which can be obtained by the client calling ReturnVal.getObject(). If the object could not be viewed for some reason, the ReturnVal will carry an encoded error dialog for the client to display.

view_db_object() can be done at any time, outside of the bounds of any transaction. view_db_object() returns a snapshot of the object's state at the time the view_db_object() call is processed, and will be transaction-consistent internally.

If view_db_object() is called during a transaction, the object will be returned as it stands during the transaction.. that is, if the object has been changed during the transaction, that changed object will be returned, even if the transaction has not yet been committed, and other clients would not be able to see that version of the object.

NOTE: It is critical that any code that looks at the values of fields in a DBObject go through a view_db_object() method or else the object will not properly know who owns it, which is critical for it to be able to properly authenticate field access. Keep in mind, however, that view_db_object clones the DBObject in question, so this method is very heavyweight.

Specified by:

view_db_object in interface Session

Returns:

A ReturnVal carrying an object reference and/or error dialog

edit_db_object

public arlut.csd.ganymede.ReturnVal edit_db_object(arlut.csd.ganymede.Invid invid)

Check an object out from the database for editing. The ReturnVal returned will carry a db_object reference, which can be obtained by the client calling ReturnVal.getObject(). If the object could not be checked out for editing for some reason, the ReturnVal will carry an encoded error dialog for the client to display.

Keep in mind that only one GanymedeSession can have a particular DBEditObject checked out for editing at a time. Once checked out, the object will be unavailable to any other sessions until this session calls commitTransaction() or abortTransaction().

Specified by:

edit_db_object in interface Session

Returns:

A ReturnVal carrying an object reference and/or error dialog

create_db_object

public arlut.csd.ganymede.ReturnVal create_db_object(short type)

Create a new object of the given type. The ReturnVal returned will carry a db_object reference, which can be obtained by the client calling ReturnVal.getObject(). If the object could not be checked out for editing for some reason, the ReturnVal will carry an encoded error dialog for the client to display.

Keep in mind that only one GanymedeSession can have a particular DBEditObject checked out for editing at a time. Once created, the object will be unavailable to any other sessions until this session calls commitTransaction().

Specified by:

create_db_object in interface Session

Parameters:

type - The kind of object to create.

Returns:

A ReturnVal carrying an object reference and/or error dialog

See Also:

Session

create_db_object

public arlut.csd.ganymede.ReturnVal create_db_object(short type,
                                                     boolean embedded)

Create a new object of the given type. The ReturnVal returned will carry a db_object reference, which can be obtained by the client calling ReturnVal.getObject(). If the object could not be checked out for editing for some reason, the ReturnVal will carry an encoded error dialog for the client to display.

Keep in mind that only one GanymedeSession can have a particular DBEditObject checked out for editing at a time. Once created, the object will be unavailable to any other sessions until this session calls commitTransaction().

Parameters:

type - The kind of object to create.

embedded - If true, assume the object created is embedded and does not need to have owners set.

Returns:

A ReturnVal carrying an object reference and/or error dialog

clone_db_object

public arlut.csd.ganymede.ReturnVal clone_db_object(arlut.csd.ganymede.Invid invid)

Clone a new object from object <invid>. The ReturnVal returned will carry a db_object reference, which can be obtained by the client calling ReturnVal.getObject(). If the object could not be checked out for editing for some reason, the ReturnVal will carry an encoded error dialog for the client to display.

This method must be called within a transactional context.

Typically, only certain values will be cloned. What values are retained is up to the specific code module provided for the invid type of object.

Specified by:

clone_db_object in interface Session

Returns:

A ReturnVal carrying an object reference and/or error dialog

See Also:

Session

inactivate_db_object

public arlut.csd.ganymede.ReturnVal inactivate_db_object(arlut.csd.ganymede.Invid invid)

Inactivate an object in the database

This method must be called within a transactional context. The object's change in status will not be visible to other sessions until this session calls commitTransaction().

Objects inactivated will typically be altered to reflect their inactive status, but the object itself might not be purged from the Ganymede server for a defined period of time, to allow other network systems to have time to do accounting, clean up, etc., before a user id or network address is re-used.

Specified by:

inactivate_db_object in interface Session

Returns:

a ReturnVal object if the object could not be inactivated, or null if there were no problems

See Also:

Session

reactivate_db_object

public arlut.csd.ganymede.ReturnVal reactivate_db_object(arlut.csd.ganymede.Invid invid)

Reactivates an inactivated object in the database

This method is only applicable to inactivated objects. For such, the object will be reactivated if possible, and the removal date will be cleared. The object may retain an expiration date, however.

The client should check the returned ReturnVal's getObjectStatus() method to see whether the re-activated object has an expiration date set.

This method must be called within a transactional context. The object's change in status will not be visible to other sessions until this session calls commitTransaction().

Specified by:

reactivate_db_object in interface Session

See Also:

Session

remove_db_object

public arlut.csd.ganymede.ReturnVal remove_db_object(arlut.csd.ganymede.Invid invid)

Remove an object from the database

This method must be called within a transactional context.

Certain objects cannot be inactivated, but must instead be simply removed on demand. The active permissions for the client may determine whether a particular type of object may be removed. Any problems with permissions to remove this object will result in a dialog being returned in the ReturnVal.

This method must be called within a transactional context. The object's removal will not be visible to other sessions until this session calls commitTransaction().

Specified by:

remove_db_object in interface Session

Returns:

a ReturnVal object if the object could not be inactivated, or null if there were no problems

See Also:

Session

getSchemaXML

public arlut.csd.ganymede.ReturnVal getSchemaXML(arlut.csd.ganymede.FileReceiver receiver,
                                                 boolean logOffOnFailure)

This method is called by the XML client to initiate a dump of the server's schema definition in XML format. The FileReceiver referenced passed as a parameter to this method will be used to send the data to the client.

This method will not return until the complete schema definition in XML form has been sent to the receiver, or until an exception is caught from the receiver. The returned ReturnVal indicates the success of the file transmission.

This method is only available to a supergash-privileged GanymedeSession.

Specified by:

getSchemaXML in interface Session

getDataXML

public arlut.csd.ganymede.ReturnVal getDataXML(arlut.csd.ganymede.FileReceiver receiver,
                                               boolean logOffOnFailure)

This method is called by the XML client to initiate a dump of the entire data contents of the server. The FileReceiver referenced passed as a parameter to this method will be used to send the data to the client.

This method will not return until the complete server data dump in XML form has been sent to the receiver, or until an exception is caught from the receiver. The returned ReturnVal indicates the success of the file transmission.

This method is only available to a supergash-privileged GanymedeSession.

Specified by:

getDataXML in interface Session

getXMLDump

public arlut.csd.ganymede.ReturnVal getXMLDump(arlut.csd.ganymede.FileReceiver receiver,
                                               boolean logOffOnFailure)

This method is called by the XML client to initiate a dump of the server's entire database, schema and data, in XML format. The FileReceiver referenced passed as a parameter to this method will be used to send the data to the client.

This method will not return until the complete server data dump in XML form has been sent to the receiver, or until an exception is caught from the receiver. The returned ReturnVal indicates the success of the file transmission.

This method is only available to a supergash-privileged GanymedeSession.

Specified by:

getXMLDump in interface Session

sendXML

private arlut.csd.ganymede.ReturnVal sendXML(arlut.csd.ganymede.FileReceiver receiver,
                                             boolean sendData,
                                             boolean sendSchema,
                                             boolean logOffOnFailure)

Private server-side helper method used to transmit the server's database in XML format to an FileReceiver remote receiving interface.

getUser

arlut.csd.ganymede.DBObject getUser()

Convenience method to get access to this session's UserBase instance.

getObjects

public java.util.Vector getObjects(short baseid)

This is a method to allow code in the server to quickly and safely get a full list of objects in an object base.

This is only a server-side method. getObjects() does not do anything to check access permissions.

It is the responsiblity of the code that gets a Vector back from this method not to modify the Vector returned in any way, as it may be shared by other threads.

Any objects returned by getObjects() will reflect the state of that object in this session's transaction, if a transaction is open.

Returns:

a Vector of DBObject references.

getUserInvid

public arlut.csd.ganymede.Invid getUserInvid()

Convenience method to get access to this session's user invid.

getPersonaInvid

public arlut.csd.ganymede.Invid getPersonaInvid()

Convenience method to get access to this session's persona invid.

getContainingObj

arlut.csd.ganymede.DBObject getContainingObj(arlut.csd.ganymede.DBObject object)

This method finds the ultimate owner of an embedded object

getPerm

public arlut.csd.ganymede.PermEntry getPerm(arlut.csd.ganymede.DBObject object)

This method takes the administrator's current persona, considers the owner groups the administrator is a member of, checks to see if the object is owned by that group, and determines the appropriate permission bits for the object. getPerm() will OR any proprietary ownership bits with the default permissions to give an appopriate result.

getPerm

public arlut.csd.ganymede.PermEntry getPerm(arlut.csd.ganymede.DBObject object,
                                            short fieldId)

This method takes the administrator's current persona, considers the owner groups the administrator is a member of, checks to see if the object is owned by that group, and determines the appropriate permission bits for the field in the object.

This method duplicates the logic of getPerm(object) internally for efficiency. This method is called quite a lot in the server, and has been tuned to use the pre-calculated GanymedeSession defaultPerms and personaPerms objects which cache the effective permissions for fields in the Ganymede DBStore for the current persona.

getPerm

arlut.csd.ganymede.PermEntry getPerm(short baseID,
                                     boolean includeOwnedPerms)

This method returns the generic permissions for a object type. This is currently used primarily to check to see whether a user has privileges to create an object of a specific type.

This method takes the administrator's current persona's set of appropriate permission matrices, does a binary OR'ing of the permission bits for the given base, and returns the effective permission entry.

Parameters:

includeOwnedPerms - If true, this method will return the permission that the current persona would have for an object that was owned by the current persona. If false, this method will return the default permissions that apply to objects not owned by the persona.

getPerm

arlut.csd.ganymede.PermEntry getPerm(short baseID,
                                     short fieldID,
                                     boolean includeOwnedPerms)

This method returns the current persona's default permissions for a base and field. This permission applies generically to objects that are not owned by this persona and to objects that are owned.

This is used by the dump() code to determine whether a field should be added to the set of possible fields to be returned at the time that the dump results are being prepared.

Parameters:

includeOwnedPerms - If true, this method will return the permission that the current persona would have for an object that was owned by the current persona. If false, this method will return the default permissions that apply to objects not owned by the persona.

resetDefaultPerms

private void resetDefaultPerms()

This convenience method resets defaultPerms from the default permission object in the Ganymede database.

updatePerms

public void updatePerms(boolean forceUpdate)

This non-exported method is used to generate a comprehensive permissions matrix that applies to all objects owned by the active persona for this user.

This method is synchronized, and a whole lot of operations in the server need to pass through here to ensure that the effective permissions for this session haven't changed. This method is designed to return very quickly if permissions have not changed and forceUpdate is false.

Parameters:

forceUpdate - If false, updatePerms() will do nothing if the Ganymede permissions database has not been changed since updatePerms() was last called in this GanymedeSession.

getPersona

public arlut.csd.ganymede.DBObject getPersona()

This method gives access to the DBObject for the administrator's persona record, if any. This is used by DBSession to get the label for the administrator for record keeping.

getSession

public arlut.csd.ganymede.DBSession getSession()

This method returns a reference to the DBSession object encapsulated by this GanymedeSession object. This is intended to be used by subclasses of DBEditObject that might not necessarily be in the arlut.csd.ganymede package.

isWizardActive

public boolean isWizardActive()

Returns true if a wizard is currently interacting with the user.

See Also:

GanymediatorWizard

isWizardActive

public boolean isWizardActive(arlut.csd.ganymede.GanymediatorWizard wizard)

Returns true if a particular wizard is currently interacting with the user.

See Also:

GanymediatorWizard

getWizard

public arlut.csd.ganymede.GanymediatorWizard getWizard()

Returns the active wizard, if any, for this GanymedeSession.

See Also:

GanymediatorWizard

registerWizard

public boolean registerWizard(arlut.csd.ganymede.GanymediatorWizard wizard)

This method is used to register a wizard for this GanymedeSession.

If an active wizard is already registered, this method will return false.

See Also:

GanymediatorWizard

unregisterWizard

public void unregisterWizard(arlut.csd.ganymede.GanymediatorWizard wizard)

Unregisters a wizard from this GanymedeSession.

If there is no active wizard registered, or if the registered wizard is not equal to the wizard parameter, an IllegalArgumentException will be thrown.

See Also:

GanymediatorWizard

personaMatch

public boolean personaMatch(arlut.csd.ganymede.DBObject obj)

Returns true if the active persona has some sort of owner/access relationship with the object in question through its list of owner groups.

recursePersonasMatch

private boolean recursePersonasMatch(java.util.Vector owners,
                                     java.util.Vector alreadySeen)

Recursive helper method for personaMatch.. this method does a depth first search up the owner tree for each Invid contained in the invids Vector to see if personaInvid is a member of any of the containing owner groups.

Parameters:

owners - A vector of invids pointing to OwnerBase objects

alreadySeen - A vector of owner group Invid's that have already been checked. (For infinite loop avoidance).

Returns:

true if a match is found

recursePersonaMatch

private boolean recursePersonaMatch(arlut.csd.ganymede.Invid owner,
                                    java.util.Vector alreadySeen)

Recursive helper method for personaMatch.. this method does a depth first search up the owner tree for the owner Invid to see if personaInvid is a member of any of the containing owner groups.

Parameters:

alreadySeen - A vector of owner group Invid's that have already been checked. (For infinite loop avoidance).

Returns:

true if a match is found

isMemberAll

private boolean isMemberAll(java.util.Vector owners)

This helper method iterates through the owners vector and checks to see if the current personaInvid is a member of all of the groups through either direct membership or through membership of an owning group. This method depends on recursePersonasMatch().

filterMatch

private boolean filterMatch(arlut.csd.ganymede.DBObject obj)

This method returns true if the visibility filter vector allows visibility of the object in question. The visibility vector works by direct ownership identity (i.e., no recursing up), so it's a simple loop-di-loop.

setLastEvent

private void setLastEvent(java.lang.String text)

checklogin

void checklogin()

This private method is called by all methods in GanymedeSession that require the client to be logged in to operate.