systemic.sif.sbpframework.persist.servcie
Class DOCService

java.lang.Object
  extended by systemic.sif.sbpframework.persist.servcie.DBService
      extended by systemic.sif.sbpframework.persist.servcie.DOCService

public class DOCService
extends DBService

Author:
Joerg Huber

Constructor Summary
DOCService()
           
 
Method Summary
 void cacheObject(DOCache sifObjectToCache, java.lang.String agentId, java.lang.String applicationId, java.lang.String zoneId)
          This method will save the DOCache object with all its child elements.
 void checkAndRemoveDependency(openadk.library.SIFDataObject sifObject, java.lang.String applicationId, java.lang.String zoneId)
          This method checks if there are any objects cached that depend on this object.
 void checkAndRemoveDependency(java.lang.String sifObjectName, java.lang.String flatKey, java.lang.String applicationId, java.lang.String zoneId)
           
 java.util.List<DOCObject> extractDependentObjectsFromSIFObject(openadk.library.SIFDataObject sifObject)
          This method checks SIF Object Cache if the given sifObject has dependencies and if so it will extract all dependencies and returns them.
 java.lang.String extractFlatKey(openadk.library.SIFDataObject sifObject)
          This method attempts to extract the primary key from the SIF Object as defined by the SIF Spec and flattens it.
 BaseDAO getDAO()
           
 java.util.List<DOCObject> getDependenciesFromSIFObjectAndCache(openadk.library.SIFDataObject sifObject, java.lang.String applicationId, java.lang.String zoneId)
          This method extracts the dependency info for the given sifObject and then looks up the DOC and marks already requested dependent objects for the given zone and application.
 java.util.List<DOCache> getExpiredObjects(java.lang.String applicationId, java.lang.String agentId)
          This method returns all objects in the cache that have remaining dependencies but have an expiry date older than the current date and time.
 java.util.List<DOCObject> getNotYetRequestedObjects(java.lang.String sifObjectName, java.lang.String applicationId, java.lang.String zoneId)
          This method returns a list of DOC Objects.
 java.util.List<DOCache> getObjectsWithoutDependencies(java.lang.String sifObjectName, java.lang.String applicationId, java.lang.String agentId)
          This method gets all cached objects of a given type for a particular application and agent that have no remaining dependencies.
 boolean hasPotentialDependencies(java.lang.String sifObjectName)
          This method simply checks if the SIF object given by its name (i.e StudentSchoolEnrolment) has potential dependencies based on the metadata that is available on the object.
 void markDependentObjectAsRequested(DOCObject docObject, java.lang.String agentId, java.lang.String zoneId)
          This method updates the given docObject and marks it as requested.
 void mergeWithCachedDependencies(java.util.List<DOCObject> dependentObjectList, java.lang.String applicationId, java.lang.String zoneId)
          This method iterates through the dependentObjectList and replaces elements in that list with the requested information.
 void removeCachedObject(DOCache cacheObject)
          This method removes the given object and all its dependencies from the cache.
 DOCache retrieveCachedObject(openadk.library.SIFDataObject sifObject, java.lang.String applicationId, java.lang.String zoneId, boolean loadAll)
          This method attempts to retrieve a cached SIF Object based on the object name, object key (flatten key) and the agentId.
 DOCache retrieveCachedObject(java.lang.String sifObjectName, java.lang.String flatKey, java.lang.String applicationId, java.lang.String zoneId, boolean loadAll)
           
 void updateExpiredObjects(java.lang.String applicationId, java.lang.String agentId)
          This method updates all Cached Objects and their dependencies according to the expiry strategy.
 
Methods inherited from class systemic.sif.sbpframework.persist.servcie.DBService
commit, loadSubObject, rollback, startTransaction
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

DOCService

public DOCService()
Method Detail

getDAO

public BaseDAO getDAO()
Specified by:
getDAO in class DBService

getDependenciesFromSIFObjectAndCache

public java.util.List<DOCObject> getDependenciesFromSIFObjectAndCache(openadk.library.SIFDataObject sifObject,
                                                                      java.lang.String applicationId,
                                                                      java.lang.String zoneId)
                                                               throws javax.persistence.PersistenceException,
                                                                      java.lang.IllegalArgumentException
This method extracts the dependency info for the given sifObject and then looks up the DOC and marks already requested dependent objects for the given zone and application. The final list of DOCObject is then returned. If there are no dependent objects then an empty list is returned.

Parameters:
sifObject - The SIF Object from which all dependencies need to be returned.
applicationId - Check if dependent objects have already been requested for this application.
zoneId - Check if dependent objects have already been requested for this zone.
Returns:
See description.
Throws:
javax.persistence.PersistenceException - If there is an error in the underlying DB. The error is logged.
java.lang.IllegalArgumentException - If any of the parameters is null or empty.
java.lang.Exception - some underlying issue. Error is logged.

retrieveCachedObject

public DOCache retrieveCachedObject(openadk.library.SIFDataObject sifObject,
                                    java.lang.String applicationId,
                                    java.lang.String zoneId,
                                    boolean loadAll)
                             throws javax.persistence.PersistenceException,
                                    java.lang.IllegalArgumentException
This method attempts to retrieve a cached SIF Object based on the object name, object key (flatten key) and the agentId. Since each object can only be provided from one zone the zoneID is irrelevant and is not required to determine if an object is already cached. If the object isn't cached then null is returned. NOTE: ================================================================================================================ Only the top level object is returned. The dependent object list is not returned as part of this method!! If the entire object with its dependent objects shall be returned the loadAll parameter must be set to TRUE ================================================================================================================

Parameters:
sifObject - The SIF Object for which the DOCache info shall be returned.
applicationId - The application ID for which the DOCache info shall be returned.
zoneId - The Zone ID for which the DOCache info shall be returned.
loadAll - Indicates if all dependent objects shall be loaded into memory. This is required since information is 'lazy' loaded by hibernate.
Returns:
The DOCahce object if it exists in the cache already, null if it does not exist.
Throws:
javax.persistence.PersistenceException - If there is an error in the underlying DB. The error is logged.
java.lang.IllegalArgumentException - If any of the parameters is null or empty.
java.lang.Exception - some underlying issue. Error is logged.

retrieveCachedObject

public DOCache retrieveCachedObject(java.lang.String sifObjectName,
                                    java.lang.String flatKey,
                                    java.lang.String applicationId,
                                    java.lang.String zoneId,
                                    boolean loadAll)
                             throws javax.persistence.PersistenceException,
                                    java.lang.IllegalArgumentException
Throws:
javax.persistence.PersistenceException
java.lang.IllegalArgumentException

cacheObject

public void cacheObject(DOCache sifObjectToCache,
                        java.lang.String agentId,
                        java.lang.String applicationId,
                        java.lang.String zoneId)
                 throws javax.persistence.PersistenceException,
                        java.lang.IllegalArgumentException
This method will save the DOCache object with all its child elements. It will assign appropriate properties such as Expire Info (retrieved from the Metadata Cache), received date etc. If the given sifObjectToCache has no dependencies then it will NOT be persisted. A info message is logged in that case as this is not really an error.

Parameters:
sifObjectToCache - The object to save to the DOC.
agentId - The agent that requests this save.
applicationId - The application for which the entry is stored. Will be used to pre-populate some information.
zoneId - The zone from which the SIF Object has been received. This will be the zone from which dependent objects will be requested at some stage.
Throws:
javax.persistence.PersistenceException - If the object cannot be persisted. The error is logged.
java.lang.IllegalArgumentException - If any of the parameters is null or empty. Metadata Cache is not available.

markDependentObjectAsRequested

public void markDependentObjectAsRequested(DOCObject docObject,
                                           java.lang.String agentId,
                                           java.lang.String zoneId)
                                    throws javax.persistence.PersistenceException,
                                           java.lang.IllegalArgumentException
This method updates the given docObject and marks it as requested. (requested=true, requestDate=now). It is assumed that the object does already exist (i.e must have the property id of not null). This method is intended to be called once a dependent object has been requested, meaning an appropriate SIFQuery has been issued by an agent (agentId) to a zone (zoneId).

Parameters:
docObject - The dependent object to update (must have an id of not null!!)
agentId - The agent that has requested the object.
zoneId - The zone to which the request has been sent.
Throws:
javax.persistence.PersistenceException - If the object cannot be persisted. The error is logged.
java.lang.IllegalArgumentException - If any of the parameters is null or empty. The property docObject.id is null.

mergeWithCachedDependencies

public void mergeWithCachedDependencies(java.util.List<DOCObject> dependentObjectList,
                                        java.lang.String applicationId,
                                        java.lang.String zoneId)
                                 throws javax.persistence.PersistenceException,
                                        java.lang.IllegalArgumentException
This method iterates through the dependentObjectList and replaces elements in that list with the requested information. This includes if the object has already been requested, when and by which agent. Objects that have not been requested are updated with the application ID and Zone Id. If the dependentObjectList is null or empty then no action is taken. For this method to work the following property in each DOCObject of the dependentObjectList must be populated: - objectKeyValue - sifObjectName

Parameters:
dependentObjectList - The list of objects to test
applicationId - The application to test for.
zoneId - The zone to test for.
Throws:
javax.persistence.PersistenceException - If there are any errors with the underlying data store. Error is logged.
java.lang.IllegalArgumentException - applicationId or zoneId is empty or null.

checkAndRemoveDependency

public void checkAndRemoveDependency(openadk.library.SIFDataObject sifObject,
                                     java.lang.String applicationId,
                                     java.lang.String zoneId)
                              throws java.lang.IllegalArgumentException,
                                     javax.persistence.PersistenceException
This method checks if there are any objects cached that depend on this object. If it finds any objects it will remove that dependency from the DOC. If there are no dependencies no action is taken.

Parameters:
sifObject - The object for which it is checked if there are dependencies.
applicationId - The application for which to check.
zoneId - The zone this object has been received from.
Throws:
javax.persistence.PersistenceException - If there are any errors with the underlying data store. Error is logged.
java.lang.IllegalArgumentException - sifObject, applicationId or zoneId is empty or null. Metadata Cache is not available.

checkAndRemoveDependency

public void checkAndRemoveDependency(java.lang.String sifObjectName,
                                     java.lang.String flatKey,
                                     java.lang.String applicationId,
                                     java.lang.String zoneId)
                              throws java.lang.IllegalArgumentException,
                                     javax.persistence.PersistenceException
Throws:
java.lang.IllegalArgumentException
javax.persistence.PersistenceException

getNotYetRequestedObjects

public java.util.List<DOCObject> getNotYetRequestedObjects(java.lang.String sifObjectName,
                                                           java.lang.String applicationId,
                                                           java.lang.String zoneId)
                                                    throws java.lang.IllegalArgumentException,
                                                           javax.persistence.PersistenceException
This method returns a list of DOC Objects. The objects are those that have not been requested, yet (requested=false). The 'keyForDependentObject' of each DOCObject in the list is also populated with the key details of the object. Based on this a SIF Query could easily be constructed as all the key information (xpath and value) is available after a call to this method. Note: If an agent subscribes to more than one zone for the same sifObject then this method must be called separately for each zone by the agent. If there are no cached and not yet requested objects for the given parameters then an empty list is returned.

Parameters:
sifObjectName - The SIF Object names to search for (i.e StudentPersonal)
applicationId - Only return objects marked for this application.
zoneId - Only return objects marked for this zone.
Returns:
See description
Throws:
java.lang.IllegalArgumentException - docObject is null or any of the properties listed above is empty or null. Metadata Cache is not available.
javax.persistence.PersistenceException - A database error occurred.

getObjectsWithoutDependencies

public java.util.List<DOCache> getObjectsWithoutDependencies(java.lang.String sifObjectName,
                                                             java.lang.String applicationId,
                                                             java.lang.String agentId)
                                                      throws java.lang.IllegalArgumentException,
                                                             javax.persistence.PersistenceException
This method gets all cached objects of a given type for a particular application and agent that have no remaining dependencies. These are the candidates do be removed later and be processed by the appropriate subscriber. If there are no Cached Objects without dependencies then an empty list is returned.

Parameters:
sifObjectName - The type of cached objects to be returned.
applicationId - The application for which the objects shall be returned.
agentId - The agent for which to get the object list.
Returns:
See description.
Throws:
java.lang.IllegalArgumentException - Any of the parameters is null or empty.
javax.persistence.PersistenceException - A database error occurred. Error is logged.

getExpiredObjects

public java.util.List<DOCache> getExpiredObjects(java.lang.String applicationId,
                                                 java.lang.String agentId)
                                          throws java.lang.IllegalArgumentException,
                                                 javax.persistence.PersistenceException
This method returns all objects in the cache that have remaining dependencies but have an expiry date older than the current date and time. These are the candidates that need to either be removed or re-requested by the agent. If there are no expired objects then an empty list is returned.

Parameters:
applicationId - Only return expired objects for this application.
agentId - Only return expired object that were initially cached by this agent.
Returns:
See description.
Throws:
java.lang.IllegalArgumentException - Any of the parameters is null or empty.
javax.persistence.PersistenceException - A database error occurred. Error is logged.

removeCachedObject

public void removeCachedObject(DOCache cacheObject)
                        throws javax.persistence.PersistenceException
This method removes the given object and all its dependencies from the cache. If the object is null then no action is taken.

Parameters:
cacheObject - The object to remove from the DO Cache.
Throws:
javax.persistence.PersistenceException - A database error occurred.

updateExpiredObjects

public void updateExpiredObjects(java.lang.String applicationId,
                                 java.lang.String agentId)
                          throws java.lang.IllegalArgumentException,
                                 javax.persistence.PersistenceException
This method updates all Cached Objects and their dependencies according to the expiry strategy. Currently there are 2 strategies supported: EXPIRE and REQUEST. In case of EXPIRE the cached object and its dependencies will be removed from the cache and a info message is logged. In case of REQUEST all dependent objects for each cached object will be marked as not requested (requested=false), so that it can be requested again by the appropriate subscribers. The Cached Object will update its expiry date accordingly.

Parameters:
applicationId - Only update/remove expired objects for this application.
agentId - Only update/remove expired object that were initially cached by this agent.
Throws:
java.lang.IllegalArgumentException - Any of the parameters is null or empty.
javax.persistence.PersistenceException - A database error occurred. Error is logged.

hasPotentialDependencies

public boolean hasPotentialDependencies(java.lang.String sifObjectName)
This method simply checks if the SIF object given by its name (i.e StudentSchoolEnrolment) has potential dependencies based on the metadata that is available on the object. TRUE is returned if the object has dependencies defined in the metadata cache. False is returned if there are no known dependencies based on the metadata cache (i.e StudentPersonal has no dependencies where as the StudentSchoolEnrollment has the student and school as dependencies.). If the sifObjectName is null or not known in the metadata cache then FALSE is returned, indicating no caching required.

Parameters:
sifObjectName - The name of the SIF Object to test for.
Returns:
See description.

extractFlatKey

public java.lang.String extractFlatKey(openadk.library.SIFDataObject sifObject)
                                throws java.lang.IllegalArgumentException
This method attempts to extract the primary key from the SIF Object as defined by the SIF Spec and flattens it. If the key is made up of more than one component the various components are separated by a separator as defined in the Metadata cache (generally a '|' character). The order of the key components is the same as the order of the key definition in the SIF Spec.

Parameters:
sifObject - From which the primary key shall be extracted and flattened.
Returns:
The flattened key of the SIFObject as described above.
Throws:
java.lang.IllegalArgumentException - Object is null or doesn't contain the primary key as expected by the SIF Spec.

extractDependentObjectsFromSIFObject

public java.util.List<DOCObject> extractDependentObjectsFromSIFObject(openadk.library.SIFDataObject sifObject)
                                                               throws javax.persistence.PersistenceException,
                                                                      java.lang.IllegalArgumentException
This method checks SIF Object Cache if the given sifObject has dependencies and if so it will extract all dependencies and returns them. Each dependency is taken from the sifObject content by means of looking up the SIF Object cache and its object metadata information.

Throws:
javax.persistence.PersistenceException - If there are any errors with the underlying data store. Error is logged.
java.lang.IllegalArgumentException - Metadata Cache is not available. Error is logged.