Using Java with Caché Jalapeño
Jalapeño Runtime Library Reference
[Back] 
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter provides detailed information about the following classes and interfaces in package com.jalapeno:

ApplicationContext Class
This class implements several options for connecting to a database and obtaining an instance of ObjectManager. For example, the following code creates an instance of ObjectManager and passes it an existing Connection object:
Class.forName ("com.intersys.jdbc.CacheDriver");
Connection conn = DriverManager.getConnection (url, username, pwd);
objManager = ApplicationContext.createObjectManager (conn);

The ApplicationContext class provides the following methods:
close()
Closes the object.
ApplicationContext.close()
Throws:
java.lang.Exception
createObjectManager()
Creates an ObjectManager instance. This method has the following overloads:
createObjectManager()
This overload creates an instance of ObjectManager using default settings.
ObjectManager myObjMgr = ApplicationContext.createObjectManager()
Returns:
an instance of ObjectManager.
Throws:
java.lang.Exception
createObjectManager(connection)
This overload creates an instance of ObjectManager using an existing Connection object.
ObjectManager myObjMgr = ApplicationContext.createObjectManager(connection)
Parameter:
Returns:
an instance of ObjectManager.
Throws:
java.lang.Exception
createObjectManager(mode)
This overload creates an instance of ObjectManager of a particular type (full or light).
ObjectManager myObjMgr = ApplicationContext.createObjectManager(mode)
Parameter:
Returns:
an instance of ObjectManager.
Throws:
java.lang.Exception
createObjectManager(connection, mode)
This overload creates an instance of ObjectManager with an existing connection and a specific mode.
ObjectManager myObjMgr = ApplicationContext.createObjectManager(connection, mode)
Parameters:
Returns:
an instance of ObjectManager.
Throws:
java.lang.Exception
createObjectManager(url, username, password)
This overload creates an instance of ObjectManager using standard JDBC connection information.
ObjectManager myObjMgr = 
    ApplicationContext.createObjectManager(url, username, password)
See Creating a Persistence Manager for an example.
Parameters:
Returns:
an instance of ObjectManager.
Throws:
java.lang.Exception
createObjectManager(url, username, password, mode)
This overload creates an instance of ObjectManager with a specific mode and standard JDBC connection information.
ObjectManager myObjMgr = 
   ApplicationContext.createObjectManager(url, username, password, mode)
Parameters:
Returns:
an instance of ObjectManager.
Throws:
java.lang.Exception
defaultSettings()
Returns the current default ObjectManager settings.
Settings mySettings = ApplicationContext.defaultSettings()
Settings include Fetch Policy, Client Cache Type, default ClassLoader.
Returns:
an instance of Settings used by this instance of ApplicationContext.
See Also:
ObjectManager.settings
isOpen()
Determines whether or not there is an open connection.
boolean myIsOpen = ApplicationContext.isOpen()
Returns:
Boolean true if there is open connection to the database, false otherwise.
setConnectionOptions()
Sets default connection parameters to be used by this instance of ApplicationContext.
ApplicationContext.setConnectionOptions(url, username, password)
Parameters:
setDataSource()
Uses information from an existing JDBC DataSource object to set the default connection parameters that will be used by this instance of ApplicationContext.
ApplicationContext.setDataSource(dataSource)
Parameter:
setProperties()
Uses a predefined Properties object to set the default ObjectManager properties that will be used by this instance of ApplicationContext.
ApplicationContext.setProperties(properties)
Parameter:
ObjectManager Interface
ObjectManager is an API definition for objects that store and manipulate POJOs in a database.
The ObjectManager interface specifies the following methods:
accepts()
Returns true if the given Connection object has an open connection to the database.
Static boolean myGoodConnection = ObjectManager.accepts(connection)
Parameter:
Returns:
Static boolean true if the Connection object has an open connection to the database, false otherwise.
attach()
Attaches a POJO to a persistent context without saving it.
ObjectManager.attach(pojo)
If pojo was previously attached (e.g. obtained one of the open() methods of the ObjectManager), saved, or attached and purged later, then it is reattached. The same happens if it was attached in an earlier session using another instance of ObjectManager. For an attached POJO, this method does nothing. For a new POJO, this method creates a proxy object.
All changes in pojo are merged into the corresponding proxy object in this method call.
Parameter:
Throws:
java.lang.Exception
close()
Closes an ObjectManager and marks it as unusable.
ObjectManager.close()
See Creating a Persistence Manager for an example.
All resources used by ObjectManager are cleaned up. If an underlying JDBC connection was created by ObjectManager itself, it is also closed. If ObjectManager was created on top of an existing JDBC connection, the underlying connection is not closed.
Throws:
java.lang.Exception
commit()
Commits the transaction.
ObjectManager.commit()
See Performing Transactions for an example.
If ObjectManager is not inside a transaction, then each save(), insert(), or update() starts its own transaction. The transaction can also be controlled via the underlying JDBC connection, which may be preferable in a container environment where transactions are controlled by the container.
Throws:
java.lang.Exception — Thrown if ObjectManager is not connected, or not inside a transaction, or an error occurred committing the transaction.
detach()
Ensures that all data in the given object (including all objects reachable from it by following references) can be accessed without a connection to the database.
Object detach(pojo)
The object returned from this method is associated with the same persistent instance in the database, but is guaranteed to contain all data, to be an instance of a user defined data class (rather than a subclass of it) and to refer only to such objects.
This method is only useful if the Fetch Policy used is LAZY. If the policy is EAGER then all instances returned by ObjectManager are detached objects.
Note:
This method can potentially retrieve a very large amount of data and cause an OutOfMemoryError.
Parameter:
Returns:
an object that is an instance of a user defined POJO class. It may be the same object as the given parameter, or a different one.
Throws:
java.lang.Exception
See Also:
Settings.setFetchPolicy, swizzle
extentManager()
Provides an instance of the ExtentManager interface to manage a database extent by performing operations such as killing an extent, rebuilding indices, or populating an extent with test data.
ExtentManager myObjMgr = ObjectManager.extentManager()
See Database Maintenance with ObjectManager.extentManager for a complete description with examples.
Returns:
an instance of ExtentManager
flush()
Synchronizes the persistence context with the underlying database.
ObjectManager.flush()
Throws:
java.lang.Exception
getId()
Returns the internal database Id of the given object.
java.io.Serializable myId = ObjectManager.getId(pojo)
See Accessing Objects by Id for an example.
If the pojo object is attached, then the Id of the corresponding proxy is returned. A detached object can be reattached with the attach method.
For a detached object, the Id value is returned if the object class has a placeholder for an internal Id (see the @ID annotation for more information). Otherwise, null is returned for the detached object.
Parameter:
Returns:
The internal database Id of the given object. Usually represented as java.lang.String, or in some cases as java.lang.Integer.
Throws:
java.lang.Exception
See Also:
getPrimaryKey, attach
getPrimaryKey()
Returns the primary key of the given object.
Object myPrimeKey = ObjectManager.getPrimaryKey(pojo)
See Accessing Objects by Primary Key for an example.
The result may be an instance of some class that provides detailed information about this primary key. The return value of this method is accepted as an argument to the openByPrimaryKey and removeFromDatabaseByPrimaryKey methods. A string representation of the value obtained by calling the toString() method is also accepted as an argument to those methods.
Parameter:
Returns:
the primary key of the given object, possibly represented as instance of a special class.
Throws:
java.lang.Exception
See Also:
getId, openByPrimaryKey, removeFromDatabaseByPrimaryKey
insert()
Creates a new instance in a database corresponding to a given POJO.
java.io.Serializable myInsert = ObjectManager.insert(pojo, deep)
See Creating or Updating an Object for an example.
Parameters:
Returns:
the Id of the newly created pojo instance.
Throws:
java.lang.Exception — Thrown if an error occurred while saving an object (for instance if a constraint violation is encountered, such as an object with the same primary key already existing in the database).
See Also:
save, update
isInTransaction()
Returns true if ObjectManager is in a transaction.
boolean myInTrans = ObjectManager.isInTransaction()
See Performing Transactions for an example.
Returns the true transactional state of the ObjectManager, regardless how transactions are controlled, by querying the ObjectManager or the JDBC Connection object. If ObjectManager is not inside a transaction then each save(), insert(), or update() starts its own transaction.
Returns:
True if ObjectManager is in a transaction, false otherwise.
Throws:
java.lang.Exception
isOpen()
Returns true if the ObjectManager has an open connection to the database.
boolean myIsOpen = ObjectManager.isOpen() 
Returns:
Boolean true if there is open connection to the database, false otherwise.
Throws:
java.lang.Exception
openById()
Opens an object by Id.
Object myObject = ObjectManager.openById(
   Class clazz,
   Object id)
See Accessing Objects by Id for an example.
Parameters:
Returns:
an object with the given class and id.
Throws:
java.lang.Exception
openByPrimaryKey()
Finds an object with a given key value in the data store and instantiates it in JVM memory.
Object myObject = ObjectManager.openByPrimaryKey(
   Class clazz,
   Object primaryKey)
See Accessing Objects by Primary Key for an example.
This method accepts a primaryKey value in any of the following forms:
Parameters:
Returns:
an object with the given class and primary key.
Throws:
java.lang.Exception — Thrown if a problem occurred opening the object, or an object with a given key value does not exist.
openByQuery()
Opens objects specified by an SQL query. See Opening Objects by Query for examples. This method has the following overloads:
openByQuery(clazz, sqlCondition, args)
This overload opens all objects of a given class that satisfy a simple condition specified in SQL syntax.
Iterator myIterator = ObjectManager.openByQuery(
   Class clazz,
   String sqlCondition,
   Object[] args)
See Opening Objects by Query for an example.
If the actual object belongs to a subclass of clazz, it will be opened correctly, but performance can degrade significantly when there are many such objects.
The condition supplied to this method may only refer to properties of a single object (a single row in one SQL table). For example, for class Sample.Person, valid conditions can be "Name %STARTSWITH ?", "Home_City = ?" or "ID BETWEEN ? AND ?". It can also include a "ORDER BY" clause, such as: "Home_City = ? ORDER BY Name". If a particular ordering was specified in the SQL statement, the ordering is preserved by Iterator.
When a more complex condition is required, use the openByQuery(String,Object[]) syntax.
Parameters:
Returns:
a java.util.Iterator that iterates over all opened objects in the specified order.
Throws:
java.lang.Exception
openByQuery(sqlQuery, args)
This overload opens all objects as POJOs (if the POJO class is available) that satisfy a given SQL query.
Iterator myIterator = ObjectManager.openByQuery(
   String sqlQuery,
   Object[] args)
See Opening Objects by Query for an example.
The SQL statement must satisfy the following requirements:
Here is an example of a SQL statement that opens objects of class Sample.Employee:
   SELECT Sample.Employee.%ID, Sample.Employee.Name, Sample.Company.Name 
   FROM Sample.Employee, Sample.Company 
   WHERE Revenue > ? AND Company = Sample.Company.ID 
   Order by Sample.Company.Name, Sample.Employee.Name
If actual objects belong to subclasses of the class specified by the first column of the SQL statement, they will be opened correctly, but performance can degrade significantly when there are many such objects.
Parameters:
Returns:
a java.util.Iterator that iterates over all opened objects in specified order.
Throws:
java.lang.Exception
purgeEverything()
Removes all proxy objects from memory.
ObjectManager.purgeEverything() 
Throws:
java.lang.Exception
purgeFromMemory()
Removes the association between a given instance of a POJO and any database proxies, and closes the corresponding proxy object (if any). If the connection uses Full Java Binding, the corresponding object in server memory is also closed.
ObjectManager.purgeFromMemory(pojo)
Parameter:
Throws:
java.lang.Exception — Thrown if a problems are encountered while attempting to close the associated proxy object. The exception is not thrown if a proxy object is simply not found.
refresh()
Updates the data inside a POJO to reflect any changes in the database.
ObjectManager.refresh(pojo)
Parameters:
Throws:
java.lang.Exception
removeFromDatabase()
Removes an object from the underlying data store. See Accessing Objects by Id for an example. This method has the following overloads:
removeFromDatabase(pojo)
This overload removes an object from the underlying data store. Finds a corresponding persistent database object and deletes it.
ObjectManager.removeFromDatabase(pojo)
See Accessing Objects by Id for an example.
Parameter:
Throws:
java.lang.Exception — Thrown if the delete failed, or if a corresponding database object is not found
removeFromDatabase(clazz, id)
This overload removes an instance of class clazz with Id id from the underlying data store.
ObjectManager.removeFromDatabase(
   Class clazz,
   Object id)
See Accessing Objects by Id for an example.
Parameters:
Throws:
java.lang.Exception — Thrown if the delete failed, or if a corresponding database object is not found.
removeFromDatabaseByPrimaryKey()
Removes an instance of class clazz with primary key key from the underlying data store.
ObjectManager.removeFromDatabaseByPrimaryKey(
   Class clazz,
   Object key)
See Accessing Objects by Primary Key for an example.
This method accepts a key value in any of the following forms:
Parameters:
Throws:
java.lang.Exception — Thrown if the delete failed or if a corresponding database object is not found.
rollback()
Rolls back the transaction.
ObjectManager.rollback()
See Performing Transactions for an example.
If ObjectManager is not inside a transaction, then each save(), insert(), or update() starts its own transaction.
The transaction can also be controlled via an underlying JDBC connection. This will probably be the preferred option in a container environment where transactions are controlled by the container.
Throws:
java.lang.Exception — Thrown if ObjectManager is not connected, or not inside a transaction, or an error occurred while rolling back the transaction.
save()
Creates a new instance in a database, or updates an existing one corresponding to a given POJO.
java.io.Serializable mySave = ObjectManager.save(pojo, deep)
See Creating or Updating an Object for an example.
The pojo object already exists if one of the following is true (conditions are tested in this order):
  1. pojo is attached to an existing database instance.
  2. pojo is of a class that has a placeholder for an internal Id, and its value is not null.
  3. pojo is of a class that does not have a placeholder for an internal Id, pojo itself is not attached to any new or existing database instance, and an instance with the same primary key as pojo exists in the database.
Parameters:
Returns:
the Id of the newly created database instance.
Throws:
java.lang.Exception — Thrown if an error occurred while saving the object
See Also:
insert, update, getId
settings()
Provides an instance of the Settings interface to configure settings for this instance of ObjectManager.
Settings mySettings = ObjectManager.settings()
Settings include Fetch Policy, Client Cache Type and ClassLoader. Settings can be also configured on the application level for all ObjectManager instances.
Returns:
an instance of Settings
See Also:
ApplicationContext.defaultSettings()
startTransaction()
Starts a new transaction.
ObjectManager.startTransaction()
See Performing Transactions for an example.
If ObjectManager is not inside a transaction, then each save(), insert() or update() starts its own transaction.
The transaction can also be controlled via an underlying JDBC connection. This will probably be the preferred option in a container environment where transactions are controlled by the container.
Throws:
java.lang.Exception — Thrown if ObjectManager is not connected, or is already inside a transaction, or an error occurred while starting the transaction.
swizzle()
Forces data to be fetched from the database for shadow objects used with Fetch Policy LAZY.
ObjectManager.swizzle(pojo)
If the supplied parameter is a normal POJO rather than a shadow object, this method does nothing.
After this method has completed, it is guaranteed that all properties of this object can be accessed without a request to the database, and all persistent objects referred to directly from the given object can be used without accessing the database. Direct properties of the given object can therefore be used after calling this method even if ObjectManager has disconnected from the database.
Parameter:
Throws:
java.lang.Exception
See Also:
Settings.setFetchPolicy, detach
update()
Updates an instance in the database corresponding to a given POJO.
ObjectManager.update(pojo, deep)
See Creating or Updating an Object for an example.
Parameters:
Throws:
java.lang.Exception — Thrown if an error occurred while saving object, or if an instance corresponding to pojo is not found in the database.
See Also:
insert, save
utilities()
Provides an instance of the Utilities interface to manipulate XML documents that store serialized objects.
Utilities myUtilities = ObjectManager.utilities()
See XML Serialization with ObjectManager.utilities for examples.
Returns:
an instance of Utilities
Settings Class
Provides an interface to configure settings for an instance of ObjectManager.
The Settings class provides the following methods:
clone()
Overrides clone in class Object
Object my = Settings.clone()
Returns:
a clone of this Settings object.
getClassLoader()
Returns a ClassLoader used to load data classes.
ClassLoader my = Settings.getClassLoader()
Returns:
a ClassLoader object.
setClassLoader()
Sets the values in a ClassLoader object that will be used to resolve and load data classes.
Settings.setClassLoader(classLoader)
Parameter:
getClientCacheType()
Returns a value indicating the type of caching that will be used for association of POJOs with database proxy objects.
int my = Settings.getClientCacheType()
Supported values:
Returns:
a value indicating the cache type.
setClientCacheType()
Sets the type of caching to be used for association of POJOs with database proxy objects.
int my = Settings.setClientCacheType(int clientCacheType)
See getClientCacheType for a list of supported values.
Parameter:
Returns:
the old value of the cache type.
getFetchPolicy()
Returns the value of the current fetch policy.
int my = Settings.getFetchPolicy()
Supported values:
Returns:
the value of the current fetch policy.
See Also:
ObjectManager.swizzle, ObjectManager.detach
setFetchPolicy()
Sets Fetch Policy to use.
int my = Settings.setFetchPolicy(int fetchPolicy)
See getFetchPolicy for a list of supported values.
Parameter:
Returns:
the old value of the fetch policy.
Utilities Interface
Provides an interface to manipulate XML documents that store serialized objects. See XML Serialization with ObjectManager.utilities for a complete description with examples.
The Utilities interface specifies the following methods:
addToXMLDocument()
Adds an XML representation of a given object to an XML document.
Utilities.addToXMLDocument(
   Object xmlDocument, 
   Object pojo) 
See Creating an XML Document for an example.
Note:
If the pojo object has been changed, calls to this method may cause the changes to be saved in the database.
Parameters:
Throws:
java.lang.Exception
See Also:
serializeToXML
closeXMLDocument()
Closes an XML document and produces a string representation of the document.
String my = Utilities.closeXMLDocument(Object xmlDocument) 
See Creating an XML Document for an example.
Parameter:
Returns:
a string representation of the XML document.
Throws:
java.lang.Exception
See Also:
startXMLDocument, addToXMLDocument
readFromXML()
Deserializes an XML string and creates an object in the database. The class must support XML serialization. A newly created object is not guaranteed to be saved in the database.
Object my = Utilities.readFromXML(
   Class aClass, 
   String xml) 
See Reading Serialized Objects for an example.
Parameters:
Returns:
a deserialized instance of class aClass.
Throws:
java.lang.Exception
serializeToXML()
Creates an XML representation of a given object as a string, optionally specifying the character encoding and namespace to be used. See Writing an XML String for an example. This method has the following overloads:
serializeToXML(pojo, charset, namespace)
This overload creates an XML representation of a given object as a string, specifying the character encoding and namespace to be used. The object must be XML serializable.
String my = Utilities.serializeToXML(
   Object pojo, 
   String charset, 
   String namespace) 
See Writing an XML String for an example.
Note:
If the pojo object has been changed, calls to this method may cause the changes to be saved in the database.
Parameters:
Returns:
An XML representation of a given object as a string.
Throws:
java.lang.Exception
See Also:
addToXMLDocument
serializeToXML(pojo)
This overload creates an XML representation of a given object as a string, using the default character encoding and namespace. The object must be XML serializable.
String my = Utilities.serializeToXML(Object pojo) 
See Writing an XML String for an example.
Note:
If the pojo object has been changed, calls to this method may cause the changes to be saved in the database.
Parameter:
Returns:
An XML representation of a given object as a string.
Throws:
java.lang.Exception
startXMLDocument()
Creates an XML document that can contain serialized representations of objects.
Object myDoc = Utilities.startXMLDocument(
   String rootTag, 
   String charset, 
   String namespace) 
See Creating an XML Document for an example.
This method creates an instance of an XML document. The addToXMLDocument method is used to serialize objects in this document. The closeXMLDocument method is used to obtain a string representation of the XML text in this document.
Parameters:
Returns:
an instance of an XML document.
Throws:
java.lang.Exception
ExtentManager Interface
Provides an interface to manage database extents. See Database Maintenance with ObjectManager.extentManager for a complete description with examples.
The ExtentManager interface specifies the following methods:
deleteClassDefinition()
Deletes the definition of the given class.
ExtentManager.deleteClassDefinition(Object aClass)
See Database Maintenance with ObjectManager.extentManager for an example.
Parameter:
Throws:
java.lang.Exception
getNumberOfInstances()
Returns the number of instances of the class and its subclasses currently in the database.
ExtentManager.getNumberOfInstances(Object aClass)
Parameter:
Throws:
java.lang.Exception
killExtent()
Deletes all instances of the class (and its subclasses) from the database.
ExtentManager.killExtent(Object aClass) 
See Database Maintenance with ObjectManager.extentManager for an example.
Parameter:
Throws:
java.lang.Exception
populate()
Creates randomly populated instances of the given class in the database. This method has the following overloads:
populate(aClass, numInstances)
This overload attempts to create numInstances randomly populated instances of the given class in the database. Other classes referenced by the specified class are not populated.
int myCount = ExtentManager.populate(
   Object aClass, 
   int numInstances) 
See Database Maintenance with ObjectManager.extentManager for an example.
Parameters:
Returns:
the number of instances actually created.
Throws:
java.lang.Exception
populate(classes, numRootInstances, relationFactor)
This overload attempts to create numRootInstances randomly populated instances of each of the given classes in the database. For each created instance, attempts to create relationFactor instances of each referenced child class.
Map myCount = ExtentManager.populate(
   Collection classes, 
   int numRootInstances,
   int relationFactor) 
Parameters:
Returns:
a map.
Throws:
java.lang.Exception
populate(classes, numRootInstances, relationFactor, doAction)
This overload attempts to create numRootInstances randomly populated instances of the given class in the database. For each created instance, attempts to create relationFactor instances of each referenced child class.
Map myCount = ExtentManager.populate(
   Collection classes, 
   int numRootInstances,
   int relationFactor,
   boolean doAction) 
Parameters:
Returns:
a map.
Throws:
java.lang.Exception
rebuildIndices()
Rebuilds all entries for each index that originates in the class.
ExtentManager.rebuildIndices(Class aClass)
See Database Maintenance with ObjectManager.extentManager for an example.
Parameter:
Throws:
java.lang.Exception — Thrown if indices could not be successfully rebuilt.