org.openmrs.api.db
Interface SerializedObjectDAO

All Known Implementing Classes:
HibernateSerializedObjectDAO

public interface SerializedObjectDAO

The SerializedObjectDAO is meant to be used as a means for persisting objects for which a typical relational table model is impractical. A typical example is for persisting multiple different user-configurable implementations of a particular interface. Because it is impossible to know what properties a given implementation will have and which will need to be persisted, it might be more practical to use serialization for this. Each available method for managing Serialized Objects on this class is available in two forms. The first form operates on OpenmrsObject instances directly, and isolates the consumer completely from the mechanics of Serialization. You pass in OpenmrsObjects and you get out OpenmrsObjects. For example:

 MyOpenmrsObject m = getObject(MyOpenmrsObject.class, 10);
 
The second form operates on SerializedObject instances directly, and provides the consumer with more control over how to handle these SerializedObjects. A typical reason why this might be useful is to provide graceful failure in the event that a persisted Object has had an API change, and thus would fail to deserialize properly. In this case, the consumer can use something like the following:
 MyOpenmrsObject m = null;
 SerializedObject s = getSerializedObject(10);
 try {
     m = convertSerializedObject(MyOpenmrsObject.class, s);
 }
 catch (Exception e) {
     // Handle this exception however you need to for your use case.
 }
 

Since:
1.5

Method Summary
<T extends OpenmrsObject>
T
convertSerializedObject(java.lang.Class<T> clazz, SerializedObject serializedObject)
          Converts a raw SerializedObject to an OpenmrsObject, using the appropriate Serializer
<T extends OpenmrsObject>
java.util.List<T>
getAllObjects(java.lang.Class<T> type)
          Retrieves all non-retired objects of the passed type from the database that have been saved through serialization
<T extends OpenmrsObject>
java.util.List<T>
getAllObjects(java.lang.Class<T> type, boolean includeRetired)
          Retrieves all objects from the database that match the passed type that have been saved through serialization Returns voided / retired Objects only if includeRetired parameter is true
<T extends OpenmrsMetadata>
java.util.List<T>
getAllObjectsByName(java.lang.Class<T> type, java.lang.String name, boolean exactMatchOnly)
          Retrieves all objects from the database that match the passed type and name that have been saved through serialization
 java.util.List<SerializedObject> getAllSerializedObjects(java.lang.Class<?> type, boolean includeRetired)
          Retrieves all raw Serialized Object from the database that match the passed type and includeRetired flag
 java.util.List<SerializedObject> getAllSerializedObjectsByName(java.lang.Class<?> type, java.lang.String name, boolean exactMatchOnly)
          Retrieves all raw Serialized Objects from the database that match the passed type and name
<T extends OpenmrsObject>
T
getObject(java.lang.Class<T> type, java.lang.Integer id)
          Retrieves the saved object of the passed type from the database by it's id
<T extends OpenmrsObject>
T
getObjectByUuid(java.lang.Class<T> type, java.lang.String uuid)
          Retrieves the saved object of the passed type from the database by it's uuid
 java.lang.Class<? extends OpenmrsObject> getRegisteredTypeForObject(OpenmrsObject object)
          Returns the registered class for the passed object, or null if none found For example, if the supportedTypes property contains the CohortDefinition.class interface, and a particular implementation of that interface is passed in, then this method would return CohortDefinition.class.
 SerializedObject getSerializedObject(java.lang.Integer id)
          Retrieves the raw SerializedObject from the database by id
 SerializedObject getSerializedObjectByUuid(java.lang.String uuid)
          Retrieves the raw Serialized Object from the database by uuid
 java.util.List<java.lang.Class<? extends OpenmrsObject>> getSupportedTypes()
           
 void purgeObject(java.lang.Integer id)
          Deletes the item from the database with the given primary key id
 void registerSupportedType(java.lang.Class<? extends OpenmrsObject> clazz)
          Registers a class as one that should be supported
<T extends OpenmrsObject>
T
saveObject(T object)
          Saves an object to the database in serialized form
<T extends OpenmrsObject>
T
saveObject(T object, OpenmrsSerializer serializer)
          Saves an object to the database, in serialized form, using the specified OpenmrsSerializer
 void unregisterSupportedType(java.lang.Class<? extends OpenmrsObject> clazz)
          Removes this class as one that should be supported
 

Method Detail

getSerializedObject

SerializedObject getSerializedObject(java.lang.Integer id)
                                     throws DAOException
Retrieves the raw SerializedObject from the database by id

Parameters:
id - the id to lookup
Returns:
the SerializedObject with the given id
Throws:
DAOException
Expected behavior:
return the saved serialized object

getObject

<T extends OpenmrsObject> T getObject(java.lang.Class<T> type,
                                      java.lang.Integer id)
                                  throws DAOException
Retrieves the saved object of the passed type from the database by it's id

Parameters:
type - The class of the object to retrieve
id - The primary key id of the object to retrieve
Returns:
the saved object
Throws:
DAOException
Expected behavior:
return the saved object

getSerializedObjectByUuid

SerializedObject getSerializedObjectByUuid(java.lang.String uuid)
                                           throws DAOException
Retrieves the raw Serialized Object from the database by uuid

Parameters:
uuid - The UUID of the object to retrieve
Returns:
the SerializedObject with the given uuid
Throws:
DAOException
Expected behavior:
return the saved serialized object

getObjectByUuid

<T extends OpenmrsObject> T getObjectByUuid(java.lang.Class<T> type,
                                            java.lang.String uuid)
                                        throws DAOException
Retrieves the saved object of the passed type from the database by it's uuid

Parameters:
type - The class of the object to retrieve
uuid - The UUID of the object to retrieve
Returns:
the saved object
Throws:
DAOException
Expected behavior:
return the saved object

saveObject

<T extends OpenmrsObject> T saveObject(T object)
                                   throws DAOException
Saves an object to the database in serialized form

Parameters:
object - The object to save
Returns:
the saved object
Throws:
DAOException
Expected behavior:
save the passed object if supported, throw an exception if object not supported

saveObject

<T extends OpenmrsObject> T saveObject(T object,
                                       OpenmrsSerializer serializer)
                                   throws DAOException
Saves an object to the database, in serialized form, using the specified OpenmrsSerializer

Parameters:
object - The object to save
serializer - The OpenmrsSerializer to use
Returns:
the saved object
Throws:
DAOException
Expected behavior:
save the passed object if supported, throw an exception if object not supported

getAllSerializedObjects

java.util.List<SerializedObject> getAllSerializedObjects(java.lang.Class<?> type,
                                                         boolean includeRetired)
                                                         throws DAOException
Retrieves all raw Serialized Object from the database that match the passed type and includeRetired flag

Parameters:
type - The class of the object to retrieve
includeRetired - if true includes retired/voided objects, otherwise does not
Returns:
T A list of all the saved objects that match the passed type
Throws:
DAOException
Expected behavior:
return all objects of the passed type

getAllObjects

<T extends OpenmrsObject> java.util.List<T> getAllObjects(java.lang.Class<T> type)
                                                      throws DAOException
Retrieves all non-retired objects of the passed type from the database that have been saved through serialization

Parameters:
type - The class of the object to retrieve
Returns:
T A list of all the saved objects that match the passed type
Throws:
DAOException
Expected behavior:
return all non-retired objects of the passed type

getAllObjects

<T extends OpenmrsObject> java.util.List<T> getAllObjects(java.lang.Class<T> type,
                                                          boolean includeRetired)
                                                      throws DAOException
Retrieves all objects from the database that match the passed type that have been saved through serialization Returns voided / retired Objects only if includeRetired parameter is true

Parameters:
type - The class of the object to retrieve
includeRetired - includeRetired If true, returns voided/retired objects as well
Returns:
T A list of all the saved objects that match the passed type
Throws:
DAOException
Expected behavior:
return all saved objects of the passed type if includeRetired, return only non-retired objects of the passed type if not includeRetired

getAllSerializedObjectsByName

java.util.List<SerializedObject> getAllSerializedObjectsByName(java.lang.Class<?> type,
                                                               java.lang.String name,
                                                               boolean exactMatchOnly)
                                                               throws DAOException
Retrieves all raw Serialized Objects from the database that match the passed type and name

Parameters:
type - The class of the object to retrieve
name - the name of the item to retrieve
exactMatchOnly - if true will only return exact matches
Returns:
T A list of all the saved objects that match the passed type and name
Throws:
DAOException
Expected behavior:
return all saved objects with the given type and exact name, return all saved objects with the given type and partial name

getAllObjectsByName

<T extends OpenmrsMetadata> java.util.List<T> getAllObjectsByName(java.lang.Class<T> type,
                                                                  java.lang.String name,
                                                                  boolean exactMatchOnly)
                                                              throws DAOException
Retrieves all objects from the database that match the passed type and name that have been saved through serialization

Parameters:
type - The class of the object to retrieve
name - the name of the item to retrieve
exactMatchOnly - if true will only return exact matches
Returns:
T A list of all the saved objects that match the passed type and name
Throws:
DAOException
Expected behavior:
return all saved objects with the given type and exact name, return all saved objects with the given type and partial name

convertSerializedObject

<T extends OpenmrsObject> T convertSerializedObject(java.lang.Class<T> clazz,
                                                    SerializedObject serializedObject)
                                                throws DAOException
Converts a raw SerializedObject to an OpenmrsObject, using the appropriate Serializer

Parameters:
clazz - the OpenmrsObject class to retrieve
serializedObject - the raw SerializedObject to deserialize into an OpenmrsObject
Returns:
an OpenmrsObject of the passed clazz from the passed SerializedObject
Throws:
DAOException

purgeObject

void purgeObject(java.lang.Integer id)
                 throws DAOException
Deletes the item from the database with the given primary key id

Parameters:
id - The id of the item to delete from the database
Throws:
DAOException
Expected behavior:
delete the object with the passed id

getRegisteredTypeForObject

java.lang.Class<? extends OpenmrsObject> getRegisteredTypeForObject(OpenmrsObject object)
Returns the registered class for the passed object, or null if none found For example, if the supportedTypes property contains the CohortDefinition.class interface, and a particular implementation of that interface is passed in, then this method would return CohortDefinition.class.

Parameters:
object - The object to check for the registered type
Returns:
The registered type for the passed object, or null if not found

getSupportedTypes

java.util.List<java.lang.Class<? extends OpenmrsObject>> getSupportedTypes()
Returns:
all supported types that this class can manage

registerSupportedType

void registerSupportedType(java.lang.Class<? extends OpenmrsObject> clazz)
                           throws DAOException
Registers a class as one that should be supported

Parameters:
clazz - The class to register
Throws:
DAOException

unregisterSupportedType

void unregisterSupportedType(java.lang.Class<? extends OpenmrsObject> clazz)
                             throws DAOException
Removes this class as one that should be supported

Parameters:
clazz - The class to un-register
Throws:
DAOException

OpenMRS-1.7.x

Generated Apr 27 2012 10:06 PM. NOTE - these libraries are in active development and subject to change