Platform SDK Java 8.5 API Reference

com.genesyslab.platform.applicationblocks.com
Interface IConfService

All Superinterfaces:
AsyncInvokerSupport, SubscriptionService<ConfEvent>
All Known Implementing Classes:
ConfService

public interface IConfService
extends SubscriptionService<ConfEvent>, AsyncInvokerSupport

It's a main Configuration Service interface of Configuration Object Model Application Block.
It declares operations like:

Configuration service factory ConfServiceFactory is the starting point for initialization and getting of configuration service instances.

See Also:
ConfServiceFactory

Method Summary
<T extends ICfgObject>
AsyncRequestResult<T>
beginRetrieveMultipleObjects(java.lang.Class<T> cls, ICfgQuery query, Action<AsyncRequestResult<T>> finishCallback)
          Begins to asynchronously retrieve a list of objects based on the specified query.
<T extends ICfgObject>
AsyncRequestResult<T>
beginRetrieveMultipleObjects(java.lang.Class<T> cls, ICfgQuery query, Action<java.util.Collection<T>> dataCallback, Action<AsyncRequestResult<T>> finishCallback)
          Begins to asynchronously retrieve a list of objects based on the specified query.
<T extends ICfgObject>
AsyncRequestResult<T>
beginRetrieveMultipleObjects(java.lang.Class<T> cls, ICfgQuery query, Action<java.util.Collection<T>> dataCallback, Action<AsyncRequestResult<T>> finishCallback, long timeout)
          Starts reading of configuration objects collection from server.
<T extends ICfgObject>
java.util.Collection<T>
createMultipleObjects(ConfDataCollection<? extends ConfObjectBase> confObjects, java.lang.String[] objectsPaths, int[] foldersDbids)
          Creates collection of COM configuration objects using the passed parameters.
 java.util.Collection<ICfgObject> createMultipleObjects(ConfObjectsCollection confObjects)
          Creates collection of COM configuration objects using the passed parameters.
<T extends ICfgObject>
java.util.Collection<T>
createMultipleObjectsFromXML(org.w3c.dom.Node receivedObjects)
          Creates a list of configuration objects based on XML received from Configuration Server
<T extends ICfgObject>
java.util.Collection<T>
createMultipleObjectsFromXML(org.w3c.dom.Node receivedObjects, java.lang.String[] objectPaths, int[] folderDbids)
          Creates a list of configuration objects based on XML received from Configuration Server.
 ICfgObject createObject(ConfObjectBase confObject, boolean isSaved)
          Creates a single COM configuration object using the passed parameters.
 ICfgObject createObject(ConfObjectBase confObject, java.lang.String objectPath, int folderDbid, boolean isSaved)
          Wraps a single configuration structure with COM configuration object using the passed parameters.
 ICfgObject createObjectFromXML(org.w3c.dom.Node confObject, boolean isSaved)
          Creates a single COM configuration object using the passed parameters.
 ICfgObject createObjectFromXML(org.w3c.dom.Node confObject, java.lang.String objectPath, int folderDbid, boolean isSaved)
          Creates a single COM configuration object using the passed parameters.
 void deleteObject(ICfgObject cfgObject)
          Deletes the specified object.
<T extends ICfgObject>
java.util.Collection<T>
endRetrieveMultipleObjects(AsyncRequestResult<T> asyncResult)
          Called to retrieve the result of asynchronous RetrieveMultipleObjects operation.
 IConfCache getCache()
          Returns an instance of the configuration cache or null if caching is not enabled.
 CfgMetadata getMetaData()
          Returns reference to the configuration Metadata.
 IConfServicePolicy getPolicy()
          Returns the policy associated with this service.
 Protocol getProtocol()
          Returns a reference to the protocol connection to Configuration Server.
 void refreshObject(ICfgObject cfgObject)
          Refreshes the specified object with the latest information.
<T extends ICfgObject>
java.util.Collection<T>
retrieveMultipleObjects(java.lang.Class<T> cls, ICfgQuery query)
          Retrieves a list of typed objects based on the specified query.
<T extends ICfgObject>
java.util.Collection<T>
retrieveMultipleObjects(java.lang.Class<T> cls, ICfgQuery query, long timeout)
          Retrieves a list of typed objects based on the specified query.
 ICfgObject retrieveObject(CfgObjectType objectType, int dbId)
          Retrieves an object based on its dbid and type query.
<T extends ICfgObject>
T
retrieveObject(java.lang.Class<T> cls, ICfgQuery query)
          Retrieves a typed object based on the specified query.
<T extends ICfgObject>
T
retrieveObject(ICfgQuery<T> query)
          Retrieves an object based on the specified query.
 void saveObject(ICfgObject cfgObject)
          Updates the specified object.
 void setBrokerInvoker(AsyncInvoker invoker)
          Sets user defined custom invoker for ConfEvent broker.
 void setInvoker(AsyncInvoker invoker)
          Sets user defined custom invoker for callback notifications on asynchronous multiple objects reading operations.
 void setUserMessageHandler(MessageHandler msgHandler)
          Sets extra MessageHandler for custom handling of incoming asynchronous protocol messages on the channel.
It will be called in the protocol invoker thread after procession by the ConfService internal handler.
 Subscription subscribe(ICfgObject obj)
          Subscribes to receiving notifications.
 Subscription subscribe(NotificationQuery query)
          Subscribes to receiving notifications.
 void unsubscribe(Subscription subscription)
          Unsubscribes from receiving notifications from Configuration Server.
 
Methods inherited from interface com.genesyslab.platform.applicationblocks.commons.broker.SubscriptionService
register, register, unregister, unregister
 

Method Detail

getProtocol

Protocol getProtocol()
Returns a reference to the protocol connection to Configuration Server.


getMetaData

CfgMetadata getMetaData()
Returns reference to the configuration Metadata.

Returns:
Metadata reference from the underlying protocol.

getCache

IConfCache getCache()
Returns an instance of the configuration cache or null if caching is not enabled.


getPolicy

IConfServicePolicy getPolicy()
Returns the policy associated with this service.


saveObject

void saveObject(ICfgObject cfgObject)
                throws ConfigException
Updates the specified object.

Parameters:
cfgObject - the object to update
Throws:
ConfigException - in case of problems in communication with server.
java.lang.IllegalStateException - if service is already disposed.

deleteObject

void deleteObject(ICfgObject cfgObject)
                  throws ConfigException
Deletes the specified object.

Parameters:
cfgObject - the object to delete
Throws:
ConfigException - in case of problems in communication with server.
java.lang.IllegalStateException - if service is already disposed.

refreshObject

void refreshObject(ICfgObject cfgObject)
                   throws ConfigException
Refreshes the specified object with the latest information.

Parameters:
cfgObject - the object to refresh
Throws:
ConfigException - in case of problems while reading data from server.
java.lang.IllegalStateException - if service is already disposed.

retrieveObject

<T extends ICfgObject> T retrieveObject(ICfgQuery<T> query)
                                    throws ConfigException
Retrieves an object based on the specified query.

Parameters:
query - the query by which to retrieve the object
Returns:
The retrieved object or null
Throws:
ConfigException - in case of problems while reading data from server.
java.lang.IllegalStateException - if service is already disposed.

retrieveObject

<T extends ICfgObject> T retrieveObject(java.lang.Class<T> cls,
                                        ICfgQuery query)
                                    throws ConfigException
Retrieves a typed object based on the specified query.

Type Parameters:
T - The type of object to retrieve
Parameters:
query - the query by which to retrieve the object
Returns:
The retrieved object or null
Throws:
ConfigException - in case of problems while reading data from server.
java.lang.IllegalStateException - if service is already disposed.

retrieveObject

ICfgObject retrieveObject(CfgObjectType objectType,
                          int dbId)
                          throws ConfigException
Retrieves an object based on its dbid and type query.

Parameters:
dbId - the dbid of the object to retrieve
objectType - the object's type
Returns:
the retrieved object or null
Throws:
ConfigException - in case of problems while reading data from server.
java.lang.IllegalStateException - if service is already disposed.

retrieveMultipleObjects

<T extends ICfgObject> java.util.Collection<T> retrieveMultipleObjects(java.lang.Class<T> cls,
                                                                       ICfgQuery query)
                                                                   throws ConfigException,
                                                                          java.lang.InterruptedException
Retrieves a list of typed objects based on the specified query.

Type Parameters:
T - The type of objects to retrieve
Parameters:
query - the query by which to retrieve the objects
Returns:
a list of retrieved objects or null
Throws:
ConfigException - in case of problems while reading data from server.
java.lang.IllegalArgumentException - if query type is unsupported.
java.lang.IllegalStateException - if service is already disposed.
java.lang.InterruptedException

retrieveMultipleObjects

<T extends ICfgObject> java.util.Collection<T> retrieveMultipleObjects(java.lang.Class<T> cls,
                                                                       ICfgQuery query,
                                                                       long timeout)
                                                                   throws ConfigException,
                                                                          java.lang.InterruptedException
Retrieves a list of typed objects based on the specified query.

Type Parameters:
T - The type of objects to retrieve
Parameters:
query - the query by which to retrieve the objects
timeout - timeout in milliseconds which will be used for waiting messages from server (excluding parsing time of messages)
Returns:
a list of retrieved objects or null
Throws:
ConfigException - in case of problems while reading data from server.
java.lang.IllegalArgumentException - if query type is unsupported.
java.lang.IllegalStateException - if service is already disposed.
java.lang.InterruptedException

beginRetrieveMultipleObjects

<T extends ICfgObject> AsyncRequestResult<T> beginRetrieveMultipleObjects(java.lang.Class<T> cls,
                                                                          ICfgQuery query,
                                                                          Action<AsyncRequestResult<T>> finishCallback)
                                                                      throws ConfigException
Begins to asynchronously retrieve a list of objects based on the specified query. EndRetrieveMultipleObjects should then be called, either upon callback for asynchronous notification, or immediately, which will block the calling thread until results are available. Callback notifications are done with additional invoker, so, async invoker must be set with setInvoker(AsyncInvoker) before this method invocation if we have non-null callback.

Type Parameters:
T - The type of objects to retrieve
Parameters:
query - the query by which to retrieve the objects
finishCallback - the callback to notify when retrieve operation is complete
Throws:
ConfigException - in case of problems while reading data from server.
java.lang.IllegalArgumentException - if query type is unsupported.
java.lang.IllegalStateException - if service is already disposed.
See Also:
endRetrieveMultipleObjects(AsyncRequestResult), setInvoker(AsyncInvoker)

beginRetrieveMultipleObjects

<T extends ICfgObject> AsyncRequestResult<T> beginRetrieveMultipleObjects(java.lang.Class<T> cls,
                                                                          ICfgQuery query,
                                                                          Action<java.util.Collection<T>> dataCallback,
                                                                          Action<AsyncRequestResult<T>> finishCallback)
                                                                      throws ConfigException
Begins to asynchronously retrieve a list of objects based on the specified query. EndRetrieveMultipleObjects should then be called, either upon callback for asynchronous notification, or immediately, which will block the calling thread until results are available. Callback notifications are done with additional invoker, so, async invoker must be set with setInvoker(AsyncInvoker) before this method invocation if we have non-null callback.

Type Parameters:
T - The type of objects to retrieve
Parameters:
query - the query by which to retrieve the objects
dataCallback - the callback to notify when partial data arrived
finishCallback - the callback to notify when retrieve operation is complete
Throws:
ConfigException - in case of problems while reading data from server.
java.lang.IllegalArgumentException - if query type is unsupported.
java.lang.IllegalStateException - if service is already disposed.
See Also:
endRetrieveMultipleObjects(AsyncRequestResult), setInvoker(AsyncInvoker)

beginRetrieveMultipleObjects

<T extends ICfgObject> AsyncRequestResult<T> beginRetrieveMultipleObjects(java.lang.Class<T> cls,
                                                                          ICfgQuery query,
                                                                          Action<java.util.Collection<T>> dataCallback,
                                                                          Action<AsyncRequestResult<T>> finishCallback,
                                                                          long timeout)
                                                                      throws ConfigException
Starts reading of configuration objects collection from server. Callback notifications are done with additional invoker, so, async invoker must be set with setInvoker(AsyncInvoker) before this method invocation if we have non-null callback.

Type Parameters:
T - specific wrapping class of particular configuration objects type
Parameters:
cls - class used for generic matching
query - query for objects reading
dataCallback - user defined callback action for data parts arrival notification or null
finishCallback - user defined callback action for data readiness notification or null
timeout - timeout in milliseconds which will be used for waiting messages from server (excluding parsing time of messages)
Throws:
ConfigException - in case of problems while reading data from server.
java.lang.IllegalArgumentException - if query type is unsupported.
java.lang.IllegalStateException - if service is already disposed.
See Also:
endRetrieveMultipleObjects(AsyncRequestResult), setInvoker(AsyncInvoker)

endRetrieveMultipleObjects

<T extends ICfgObject> java.util.Collection<T> endRetrieveMultipleObjects(AsyncRequestResult<T> asyncResult)
                                                                      throws ConfigException,
                                                                             java.lang.InterruptedException
Called to retrieve the result of asynchronous RetrieveMultipleObjects operation. Should be called on execution of AsyncCallback passed to BeginRetrieveMultiple objects. Will block calling thread until results are received if called before operation is completed.

Parameters:
asyncResult - The IAsyncResult object used to track the current request
Returns:
A list of retrieved objects or null
Throws:
ConfigException
java.lang.InterruptedException

setInvoker

void setInvoker(AsyncInvoker invoker)
Sets user defined custom invoker for callback notifications on asynchronous multiple objects reading operations. Invoker life cycle is under user control, so, user should dispose invoker separately from ConfService.

Specified by:
setInvoker in interface AsyncInvokerSupport
Parameters:
invoker - user defined invoker
See Also:
beginRetrieveMultipleObjects(Class, ICfgQuery, Action), beginRetrieveMultipleObjects(Class, ICfgQuery, Action, Action)

setBrokerInvoker

void setBrokerInvoker(AsyncInvoker invoker)
Sets user defined custom invoker for ConfEvent broker. Invoker life cycle is under user control, so, user should dispose invoker separately from ConfService.

Parameters:
invoker - user defined invoker
Throws:
java.lang.IllegalStateException - if service is already disposed.

createObjectFromXML

ICfgObject createObjectFromXML(org.w3c.dom.Node confObject,
                               boolean isSaved)
                               throws ConfigException
Creates a single COM configuration object using the passed parameters.

Parameters:
confObject - XML describing a single configuration object as received from Configuration Server
isSaved - Specifies whether the object has been previously saved in the configuration database
Returns:
the newly created object
Throws:
ConfigException - in case of objects instantiation problems.
java.lang.IllegalStateException - if service is already disposed.

createObjectFromXML

ICfgObject createObjectFromXML(org.w3c.dom.Node confObject,
                               java.lang.String objectPath,
                               int folderDbid,
                               boolean isSaved)
                               throws ConfigException
Creates a single COM configuration object using the passed parameters.

Parameters:
confObject - XML describing a single configuration object as received from Configuration Server
objectPath - The folder path of the object in Configuration Server
folderDbid - The DBID of the folder in which the object resides
isSaved - Specifies whether the object has been previously saved in the configuration database
Returns:
the newly created object
Throws:
ConfigException - in case of objects instantiation problems.
java.lang.IllegalStateException - if service is already disposed.

createMultipleObjectsFromXML

<T extends ICfgObject> java.util.Collection<T> createMultipleObjectsFromXML(org.w3c.dom.Node receivedObjects,
                                                                            java.lang.String[] objectPaths,
                                                                            int[] folderDbids)
                                                                        throws ConfigException
Creates a list of configuration objects based on XML received from Configuration Server.

Parameters:
receivedObjects - the XPathNavigable object in the format of the EventObjectsRead.ConfObject property
objectPaths - Array of strings representing a list of paths for the objects in receivedObjects (should be in the same order)
folderDbids - integer array of folder DBIDs, should be in the same order as the receivedObjects list
Returns:
a list of newly created objects
Throws:
ConfigException - in case of objects instantiation problems.
java.lang.IllegalStateException - if service is already disposed.

createMultipleObjectsFromXML

<T extends ICfgObject> java.util.Collection<T> createMultipleObjectsFromXML(org.w3c.dom.Node receivedObjects)
                                                                        throws ConfigException
Creates a list of configuration objects based on XML received from Configuration Server

Parameters:
receivedObjects - the XPathNavigable object in the format of the EventObjectsRead.ConfObject property
Returns:
a list of newly created objects
Throws:
ConfigException - in case of objects instantiation problems.
java.lang.IllegalStateException - if service is already disposed.

createObject

ICfgObject createObject(ConfObjectBase confObject,
                        java.lang.String objectPath,
                        int folderDbid,
                        boolean isSaved)
                        throws ConfigException
Wraps a single configuration structure with COM configuration object using the passed parameters.

Parameters:
confObject - initial content of the object to be created
objectPath - The folder path of the object in Configuration Server
folderDbid - The DBID of the folder in which the object resides
isSaved - specifies whether the object has been previously saved in the configuration database
Returns:
newly created configuration object.
Throws:
ConfigException - in case of problems in communication with server.
java.lang.IllegalStateException - if service is already disposed.
java.lang.IllegalArgumentException - if given objects structure is null or invalid.

createObject

ICfgObject createObject(ConfObjectBase confObject,
                        boolean isSaved)
                        throws ConfigException
Creates a single COM configuration object using the passed parameters.

Parameters:
confObject - initial content of the object to be created
isSaved - specifies whether the object has been previously saved in the configuration database
Returns:
newly created configuration object.
Throws:
ConfigException - in case of problems in communication with server.
java.lang.IllegalStateException - if service is already disposed.
java.lang.IllegalArgumentException - if given objects structure is null or invalid.

createMultipleObjects

<T extends ICfgObject> java.util.Collection<T> createMultipleObjects(ConfDataCollection<? extends ConfObjectBase> confObjects,
                                                                     java.lang.String[] objectsPaths,
                                                                     int[] foldersDbids)
                                                                 throws ConfigException
Creates collection of COM configuration objects using the passed parameters.

Parameters:
confObjects - collection of objects declarations to be created
Returns:
newly created configuration object.
Throws:
ConfigException - in case of problems in communication with server.
java.lang.IllegalStateException - if service is already disposed.
java.lang.NullPointerException - if given collection is null.
java.lang.IllegalArgumentException - if given object structure in the collection is null or invalid.

createMultipleObjects

java.util.Collection<ICfgObject> createMultipleObjects(ConfObjectsCollection confObjects)
                                                       throws ConfigException
Creates collection of COM configuration objects using the passed parameters.

Parameters:
confObjects - collection of objects declarations to be created
Returns:
newly created configuration object.
Throws:
ConfigException - in case of problems in communication with server.
java.lang.IllegalStateException - if service is already disposed.
java.lang.NullPointerException - if given collection is null.
java.lang.IllegalArgumentException - if given object structure in the collection is null or invalid.

subscribe

Subscription subscribe(NotificationQuery query)
                       throws ConfigException
Subscribes to receiving notifications. This method allows the user to specify the subscription details using the "NotificationQuery" object passed as a parameter.

Parameters:
query - the query specifying the subscription details
Throws:
ConfigException - in case of problems in communication with server.
java.lang.IllegalStateException - if service is already disposed.
See Also:
unsubscribe(Subscription)

subscribe

Subscription subscribe(ICfgObject obj)
                       throws ConfigException
Subscribes to receiving notifications. This method subscribes to events for the object passed as the parameter.

Parameters:
obj - the object about which we want to receive notifications
Throws:
ConfigException - in case of problems in communication with server.
java.lang.IllegalStateException - if service is already disposed.
See Also:
unsubscribe(Subscription)

unsubscribe

void unsubscribe(Subscription subscription)
                 throws ConfigException
Unsubscribes from receiving notifications from Configuration Server.

Parameters:
subscription - reference to a service subscription.
Throws:
ConfigException - in case of problems in communication with server.
java.lang.IllegalStateException - if service is already disposed.
See Also:
subscribe(ICfgObject), subscribe(NotificationQuery)

setUserMessageHandler

void setUserMessageHandler(MessageHandler msgHandler)
Sets extra MessageHandler for custom handling of incoming asynchronous protocol messages on the channel.
It will be called in the protocol invoker thread after procession by the ConfService internal handler.

Parameters:
msgHandler - user handler

Platform SDK Java 8.5 API Reference

Send comments on this topicTechpubs.webadmin@genesys.com.
Document version: 8.5.302.00
Copyright © 2006–2017 Genesys Telecommunications Laboratories, Inc. All rights reserved.