com.arsdigita.persistence
Class Session

java.lang.Object
  extended bycom.arsdigita.persistence.Session

public class Session
extends Object

All persistence operations take place within the context of a session. The operational persistence methods operate on the object types and associations defined in the Persistence Definition Langauge (PDL) files. The Session object has the operational methods for creating and retrieving data objects. The APIs that operate on the PDL-defined metadata are in the com.arsdigita.persistence.metadata package. The Session object can be retrieved from the static SessionManager.getSession() method.

Version:
$Revision: #37 $ $Date: 2004/04/07 $
Author:
rhs@mit.edu
See Also:
SessionManager

Method Summary
 DataObject create(ObjectType type)
          Creates and returns a DataObject of the given type.
 DataObject create(OID oid)
          Creates a new DataObject with the type of the given oid and initializes the key properties to the values specified in the oid.
 DataObject create(String typeName)
          Creates and returns an empty DataObject of the given type.
 boolean delete(OID oid)
          Deletes the persistent object of the given type with the given oid.
 void flushAll()
          Force all outstanding changes to be flushed to the database.
 Connection getConnection()
          Returns the JDBC connection associated with this session.
 int getDatabase()
           
 MetadataRoot getMetadataRoot()
           
 TransactionContext getTransactionContext()
          Retrieves the TransactionContext associated with this Session.
 DataCollection retrieve(ObjectType type)
          Retrieves a collection of objects of the specified objectType.
 DataObject retrieve(OID oid)
          Retrieves the DataObject specified by oid.
 DataCollection retrieve(String typeName)
          Retrieves a collection of objects of the specified objectType.
 DataOperation retrieveDataOperation(String name)
           Retrieves a DML data operation based on the named query.
 DataQuery retrieveQuery(String name)
          Retrieves a persistent query object based on the named query.
 void startProfiling()
           
 void stopProfiling()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getMetadataRoot

public MetadataRoot getMetadataRoot()

startProfiling

public void startProfiling()

stopProfiling

public void stopProfiling()

getDatabase

public int getDatabase()

getTransactionContext

public TransactionContext getTransactionContext()
Retrieves the TransactionContext associated with this Session. Every Session has exactly one TransactionContext object. The transaction context can be obtained as in this example:
   Session ssn = SessionManager.getSession();
   TransactionContext txn = ssn.getTransactionContext();
   
The TransactionContext can be used to:

Returns:
The transaction context for this Session.
See Also:
SessionManager, Connection

getConnection

public Connection getConnection()
Returns the JDBC connection associated with this session.

Returns:
The JDBC connection used by this Session object.

create

public DataObject create(ObjectType type)
Creates and returns a DataObject of the given type. All fields of this object are initially set to null, and it is not persisted until DataObject.save() is called.

Because of the initial null values, this method should only be used for creating new objects. The method retrieve(OID) is suitable for creating objects that will then be populated with information from the database (e.g. objects that are being retrieved rather than created as new).

Parameters:
type - The type of the object to be created.
Returns:
A persistent object of the specified type.
See Also:
create(String)

create

public DataObject create(String typeName)
Creates and returns an empty DataObject of the given type. The properties in the data object may then be initialized using DataObject.set(String,Object). Once this is done the object may be persisted using DataObject.save(). An example:
   Session ssn = SessionManager.getSession();
   DataObject employee = ssn.create("com.dotcom.Employee");

   employee.set("name", "John Doughnut");
   employee.set("id", new BigInteger(12345));
   employee.set("title", "Developer");

   employee.save();
   

Parameters:
typeName - The qualified name of the type of object to be created.
Returns:
A persistent object of the type identified by typeName.
See Also:
SessionManager

create

public DataObject create(OID oid)
Creates a new DataObject with the type of the given oid and initializes the key properties to the values specified in the oid.

Parameters:
oid - The OID that specifies the type of and key properties for the resulting DataObject.

retrieve

public DataObject retrieve(OID oid)
Retrieves the DataObject specified by oid. If there is no object of the given type with the given OID, then null is returned. The retrieval will be executed with the persistence mechanism assoicated with this session. Null is also returned if any of the statements in the "Retrieve" event for the data object failed.

Parameters:
oid - The id of the object to be retrieved.
Returns:
A persistent object of the type specified by the oid.

delete

public boolean delete(OID oid)
Deletes the persistent object of the given type with the given oid.

Parameters:
oid - The id of the object to be deleted.
Returns:
True of an object was deleted, false otherwise.

retrieve

public DataCollection retrieve(ObjectType type)
Retrieves a collection of objects of the specified objectType. This method executes the retrieveAll event defined in the PDL and then returns a DataCollection. This data collection can be filtered and iterated over to retrieve data for the object.

Parameters:
type - The type of the persistent collection.
Returns:
A DataCollection of the specified type.
See Also:
retrieve(String)

retrieve

public DataCollection retrieve(String typeName)

Retrieves a collection of objects of the specified objectType. This method executes the retrieveAll event defined in the PDL and then returns a DataCollection. This data collection can be filtered and iterated over to retrieve data for the object.

The retrieveAll event can be defined as in this example:
 retrieveAll {
   do {
     select *
     from users
   } map {
     firstName=users.first_name;
     lastName=users.last_name;
   }
 }
 
From Java, you can retrieve all of the users as a DataCollection, and add filters.
 DataCollection allUsers = session.retrieve("users");
 allUsers.addEqualsFilter("firstName", "Smith")
 while (allUsers.next()) {
   System.out.println(allUsers.get("firstName") +
     allUsers.get("lastName") +
     allUsers.get("groupName"));
 }
 
It is also possible to instantiate a data object from a DataCollection, using DataCollection.getDataObject().

Parameters:
typeName - The qualified name of the type of the object to be created.
Returns:
A DataCollection populated by the specified object type's retrieveAll event..
See Also:
retrieve(ObjectType)

retrieveQuery

public DataQuery retrieveQuery(String name)

Retrieves a persistent query object based on the named query. The query must be defined with the specified name in the the PDL.

DataQuery objects can be used to access fields from several data objects (representing columns in separate database tables) in a lightweight fashion. The example belows show you can use a DataQuery to access information about users and groups.

 query UsersGroups {
 do {
   select *
   from users, groups, membership
   where users.user_id = membership.member_id
   and membership.group_id = groups.group_id
 } map {
   firstName=users.first_name;
   lastName=users.last_name;
   groupName=groups.group_name;
 }
 
You can use this query and filter it further. Let's say I wanted to get all users whose first name is "Smith":
 DataQuery query = session.retrieveQuery("UsersGroups");
 query.addEqualsFilter("firstName", "Smith")
 while (query.next()) {
 System.out.println(query.get("firstName") + query.get("lastName") +
   query.get("groupName"));
 }
 
The filter will add the necessary "where" clause to the SQL. The DataQuery can then be iterated over to display the appropriate data.

Parameters:
name - The name of the query.
Returns:
A new DataQuery object.

retrieveDataOperation

public DataOperation retrieveDataOperation(String name)

Retrieves a DML data operation based on the named query. A DataOperation is used to perform an operation on the data, such as a delete or an update. The example belows shows how it can be used to delete a set of categories.

 data operation deleteCategories {
   delete from cat_categories
   where enabled_p = 0
 }

The data operation defined in the SQL is accessed with the DataOperation object.

 Sessions session = SessionManager.getSession();
 DataOperation dop = session.retreiveDataOperation("deleteCategories");
 dop.execute();
 

Parameters:
name - The name of the data operation defined in the PDL.
Returns:
A DataOperation object corresponding to the definition in the PDL.

flushAll

public void flushAll()
Force all outstanding changes to be flushed to the database. This is approximately the equivalent of calling save on every data object associated with this session.

Throws:
FlushException - when all changes can not be flushed


Copyright (c) 2004 Red Hat, Inc. Corporation. All Rights Reserved. Generated at July 21 2004:2337 UTC