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

Modifier and Type	Method and Description
<T extends OpenmrsObject> T	convertSerializedObject(Class<T> clazz, SerializedObject serializedObject) Converts a raw SerializedObject to an OpenmrsObject, using the appropriate Serializer
<T extends OpenmrsObject> List<T>	getAllObjects(Class<T> type) Retrieves all non-retired objects of the passed type from the database that have been saved through serialization
<T extends OpenmrsObject> List<T>	getAllObjects(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> List<T>	getAllObjectsByName(Class<T> type, String name, boolean exactMatchOnly) Retrieves all objects from the database that match the passed type and name that have been saved through serialization
List<SerializedObject>	getAllSerializedObjects(Class<?> type, boolean includeRetired) Retrieves all raw Serialized Object from the database that match the passed type and includeRetired flag
List<SerializedObject>	getAllSerializedObjectsByName(Class<?> type, String name, boolean exactMatchOnly) Retrieves all raw Serialized Objects from the database that match the passed type and name
<T extends OpenmrsObject> T	getObject(Class<T> type, Integer id) Retrieves the saved object of the passed type from the database by it's id
<T extends OpenmrsObject> T	getObjectByUuid(Class<T> type, String uuid) Retrieves the saved object of the passed type from the database by it's uuid
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(Integer id) Retrieves the raw SerializedObject from the database by id
SerializedObject	getSerializedObjectByUuid(String uuid) Retrieves the raw Serialized Object from the database by uuid
List<Class<? extends OpenmrsObject>>	getSupportedTypes()
void	purgeObject(Integer id) Deletes the item from the database with the given primary key id
void	registerSupportedType(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(Class<? extends OpenmrsObject> clazz) Removes this class as one that should be supported

Method Detail

getSerializedObject

SerializedObject getSerializedObject(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

Should:

return the saved serialized object

getObject

<T extends OpenmrsObject> T getObject(Class<T> type,
                                      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

Should:

return the saved object

getSerializedObjectByUuid

SerializedObject getSerializedObjectByUuid(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

Should:

return the saved serialized object

getObjectByUuid

<T extends OpenmrsObject> T getObjectByUuid(Class<T> type,
                                            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

Should:

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

Should:

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

Should:

save the passed object if supported, throw an exception if object not supported

getAllSerializedObjects

List<SerializedObject> getAllSerializedObjects(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

Should:

return all objects of the passed type

getAllObjects

<T extends OpenmrsObject> List<T> getAllObjects(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

Should:

return all non-retired objects of the passed type

getAllObjects

<T extends OpenmrsObject> List<T> getAllObjects(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

Should:

return all saved objects of the passed type if includeRetired, return only non-retired objects of the passed type if not includeRetired

getAllSerializedObjectsByName

List<SerializedObject> getAllSerializedObjectsByName(Class<?> type,
                                                     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

Should:

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> List<T> getAllObjectsByName(Class<T> type,
                                                        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

Should:

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(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(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

Should:

delete the object with the passed id

getRegisteredTypeForObject

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

List<Class<? extends OpenmrsObject>> getSupportedTypes()

Returns:

all supported types that this class can manage

registerSupportedType

void registerSupportedType(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(Class<? extends OpenmrsObject> clazz)
                      throws DAOException

Removes this class as one that should be supported

Parameters:

clazz - The class to un-register

Throws:

DAOException