IBM WebSphere Extended Deployment (XD)TM
Release 6.0

com.ibm.websphere.objectgrid
ObjectGridManager



ObjectGridManager is responsible for creating or getting an ObjectGrid instance and getting the ObjectGrid configurations.

Users can use the method #createObjectGrid(String, URL, boolean, boolean) to create an ObjectGrid instance. Users can choose to cache the created ObjectGrid instance. If users want to cache the ObjectGrid instance, they cannot create an ObjectGrid with the same name again unless they remove the previous created ObjectGrid using #removeObjectGrid(String). Users can also choose to validate the XML or not.

Users can also use other overloaded createObjectGrid and createObjectGrids methods to create ObjectGrid instances. Please look at individual methods for details.

It allows trace to be disabled completely for performance improvements especially on a processor with a smaller L2 cache.


Method Summary
public  ObjectGridcreateObjectGrid()
           A simple factory method to return an instance of an Object Grid.
public  ObjectGridcreateObjectGrid(java.lang.String, boolean)
           A simple factory method to return an instance of an ObjectGrid with the specified name.
public  ObjectGridcreateObjectGrid(java.lang.String)
           Create an ObjectGrid instance with the specified ObjectGrid name. The ObjectGrid .
public  ObjectGridcreateObjectGrid(java.lang.String, java.net.URL, boolean, boolean)
          

Create an ObjectGrid instance based on the specified ObjectGrid name and the XML file.

public  ListcreateObjectGrids(java.net.URL, boolean, boolean)
           Process an XML file and create a List of ObjectGrid objects based upon the file..
public  ListcreateObjectGrids(java.net.URL)
           Create all ObjectGrids that are found in the XML file. The XML file will be .
public  ObjectGridcreateObjectGrid(java.lang.String, java.net.URL)
           Process the XML file and create a single ObjectGrid instance with the objectGridName specified only if an ObjectGrid with that name is found in the file.
public  voidremoveObjectGrid(java.lang.String)
          
public  voidremoveObjectGrid(java.lang.String, boolean)
          
public  ListgetObjectGrids()
           Get a List of the ObjectGrid instances that have been previously cached. Returns null.
public  ObjectGridgetObjectGrid(java.lang.String)
           Use this if a ObjectGrid already exists. It returns a cached ObjectGrid instance by name. .
public  voidsetTraceSpecification(java.lang.String)
           Use this method to set the trace specification for the current JVM.
public  voidsetTraceFileName(java.lang.String)
           Use this method to have trace output to go file instead of System.out..
public  ClientClusterContextconnect(com.ibm.websphere.objectgrid.security.config.ClientSecurityConfiguration, java.net.URL)
           This method can be used only if a client is co-located with objectgrid server, especially in a J2EE environment with IBM WebSphere Application Server, which supports the embedded objectgrid server.
public  ClientClusterContextconnect(java.net.URL, java.lang.String, com.ibm.websphere.objectgrid.security.config.ClientSecurityConfiguration, java.net.URL)
          
public  ClientClusterContextconnect(java.lang.String, com.ibm.websphere.objectgrid.HostPortConnectionAttributes[], com.ibm.websphere.objectgrid.security.config.ClientSecurityConfiguration, java.net.URL)
          
public  ClientClusterContextconnect(java.lang.String, java.lang.String, java.lang.String, com.ibm.websphere.objectgrid.security.config.ClientSecurityConfiguration, java.net.URL)
           This allows client to connect to a Remote ObjectGrid
public  ObjectGridgetObjectGrid(com.ibm.websphere.objectgrid.ClientClusterContext, java.lang.String)
           Use this if a Remote ObjectGrid already exists. .
public  ObjectGridAdministratorgetObjectGridAdministrator(com.ibm.websphere.objectgrid.ClientClusterContext)
           Return an ObjectGridAdministrator instance for this cluster. Each.
public  ClustergetCluster(java.lang.String)
          

Method Detail

createObjectGrid

public ObjectGrid createObjectGrid()
A simple factory method to return an instance of an Object Grid. A unique name is assigned. The instance of ObjectGrid is not cached. Users can then use ObjectGrid#setName(String) to change the ObjectGrid name.


Returns:
     ObjectGrid an instance of ObjectGrid with a unique name assigned


Throws:
    com.ibm.websphere.objectgrid.ObjectGridException


createObjectGrid

public ObjectGrid createObjectGrid(String objectGridName,boolean cacheInstance)
A simple factory method to return an instance of an ObjectGrid with the specified name. The instances of ObjectGrid can be cached. If an ObjectGrid with the this name has already been cached, an ObjectGridException will be thrown.
Parameters:
    objectGridName - the name of the ObjectGrid to be created.
    cacheInstance - true, if the ObjectGrid instance should be cached


Returns:
     an ObjectGrid instance


Throws:
    com.ibm.websphere.objectgrid.ObjectGridException


createObjectGrid

public ObjectGrid createObjectGrid(String objectGridName)
Create an ObjectGrid instance with the specified ObjectGrid name. The ObjectGrid instance created will be cached.
Parameters:
    objectGridName - the Name of the ObjectGrid instance to be created.


Returns:
     an ObjectGrid instance


Throws:
    com.ibm.websphere.objectgrid.ObjectGridException


createObjectGrid

public ObjectGrid createObjectGrid(String objectGridName,URL xmlFile, boolean enableXmlValidation, boolean cacheInstance)

Create an ObjectGrid instance based on the specified ObjectGrid name and the XML file. The ObjectGrid instance defined in the XML file with the specified ObjectGrid name will be created and returned. If such an ObjectGrid cannot be found in the xml file, an exception will be thrown.

This ObjecGrid instance can be cached.

If the URL is null, it will be simply ignored. In this case, this method behaves the same as #createObjectGrid(String, boolean).


See Also:
    ObjectGrid
Parameters:
    objectGridName - the Name of the ObjectGrid instance to be returned. Must not be null.
    xmlFile - a URL to a wellformed xml file based on the ObjectGrid schema.
    enableXmlValidation - if true the XML is validated
    cacheInstance - a boolean value indicating whether the ObjectGrid instance(s) defined in the XML will be cached or not. If true, the instance(s) will be cached.


Returns:
     an ObjectGrid instance


Throws:
    com.ibm.websphere.objectgrid.ObjectGridException


createObjectGrids

public List createObjectGrids(URL xmlFile,boolean enableXmlValidation, boolean cacheInstances)
Process an XML file and create a List of ObjectGrid objects based upon the file. These ObjecGrid instances can be cached. An ObjectGridException will be thrown when attempting to cache a newly created ObjectGrid that has the same name as an ObjectGrid that has already been cached.
Parameters:
    xmlFile - the file that defines an ObjectGrid or multiple ObjectGrids
    enableXmlValidation - setting to true will validate the XML file against the schema
    cacheInstances - set to true to cache all ObjectGrid instances created based on the file


Returns:
     an ObjectGrid instance


Throws:
    com.ibm.websphere.objectgrid.ObjectGridException


createObjectGrids

public List createObjectGrids(URL xmlFile)
Create all ObjectGrids that are found in the XML file. The XML file will be validated against the schema. Each ObjectGrid instance that is created will be cached. An ObjectGridException will be thrown when attempting to cache a newly created ObjectGrid that has the same name as an ObjectGrid that has already been cached.
Parameters:
    xmlFile - The XML file to process. ObjectGrids will be created based on what is in the file.


Returns:
     A List of ObjectGrid instances that have been created.


Throws:
    com.ibm.websphere.objectgrid.ObjectGridException


createObjectGrid

public ObjectGrid createObjectGrid(String objectGridName,URL xmlFile)
Process the XML file and create a single ObjectGrid instance with the objectGridName specified only if an ObjectGrid with that name is found in the file. If there is no ObjectGrid with this name defined in the XML file, an ObjectGridException will be thrown. The ObjectGrid instance created will be cached.
Parameters:
    objectGridName - name of the ObjectGrid to create. This ObjectGrid should be defined in the XML file.
    xmlFile - the XML file to process


Returns:
     A newly created ObjectGrid


Throws:
    com.ibm.websphere.objectgrid.ObjectGridException


removeObjectGrid

public void removeObjectGrid(String objectGridName)
Remove an ObjectGrid from the cache of ObjectGrid instances
Parameters:
    objectGridName - the name of the ObjectGrid instance to remove from the cache


Throws:
    com.ibm.websphere.objectgrid.ObjectGridException


removeObjectGrid

public void removeObjectGrid(String objectGridName,boolean destroy)
Remove an ObjectGrid from the cache of ObjectGrid instances and destroy its associated resources
Parameters:
    objectGridName - the name of the ObjectGrid instance to remove from the cache
    destroy - destroy the objectgrid instance and its associated resources


Throws:
    com.ibm.websphere.objectgrid.ObjectGridException


getObjectGrids

public List getObjectGrids()
Get a List of the ObjectGrid instances that have been previously cached. Returns null if no ObjectGrid instances have been cached.


Returns:
     a List of ObjectGrid instances that have been previously cached


getObjectGrid

public ObjectGrid getObjectGrid(String objectGridName)
Use this if a ObjectGrid already exists. It returns a cached ObjectGrid instance by name. This method returns null if no ObjectGrid with this objectGridName has been cached.
Parameters:
    objectGridName - the cached objectgrid name.


Returns:
     a cached ObjectGrid which currently exists.


setTraceSpecification

public void setTraceSpecification(String traceSpec)
Use this method to set the trace specification for the current JVM. The specification should be of the form:

TraceString := <ComponentString>(:<ComponentString>)* ComponentString := <ComponentName>=<type>=<state>(,<type>=<state>)* ComponentName := a java String state := [enabled|disabled] type := [all|debug|event|entryExit]

For example, com.ibm.websphere.objectgrid.*=all=enabled

Parameters:
    traceSpec - Trace specification


setTraceFileName

public void setTraceFileName(String traceFileName)
Use this method to have trace output to go file instead of System.out. The supplied file name can be relative to the working directory or a fully-qualified file name.
Parameters:
    traceFileName - Name of trace file


connect

public ClientClusterContext connect(ClientSecurityConfiguration securityProps,URL overRideObjectGrid)
This method can be used only if a client is co-located with objectgrid server, especially in a J2EE environment with IBM WebSphere Application Server, which supports the embedded objectgrid server. This method connects the client to the Server which is running in the same JVM.
Parameters:
    securityProps - It can be null if not running in secure mode.
    overRideObjectGrid - xml. This parameter can be null. If it is not null, the client side configuration of objectgrid plugin is overridden. Not all plugins can be overridden. For details please see the ObjectGrid documents


Returns:
     ClientClusterContext


Throws:
    com.ibm.websphere.objectgrid.ConnectException


connect

public ClientClusterContext connect(URL clusterConfigFile,String serverName, ClientSecurityConfiguration securityProps, URL overRideObjectGrid)
This allows a client to connect to a Remote ObjectGrid
Parameters:
    clusterConfigFile - A URL to the clusterConfig File. This is the same file that is used to start servers. This is used to retrieve host port information. It cannot be null. If it is null IllegalArgumentException is thrown.
    serverName - A String, the name of the specific server to connect to. If the server name is not in the configuration, IllegalArgumentException is thrown. This parameter can be null, in which case an attempt is made to connect to one of servers specified in the cluster xml file. If an attempt fails to connect to one, another server is picked, It is done, until such time the list is exhausted.
    overRideObjectGrid - xml. This parameter can be null. If it is not null, the client side configuration of objectgrid plugin is overridden. Not all plugins can be overridden. For details please see the ObjectGrid documents


Returns:
     ClientClusterContext


Throws:
    com.ibm.websphere.objectgrid.ConnectException


connect

public ClientClusterContext connect(String clusterName,HostPortConnectionAttributes[] attributes, ClientSecurityConfiguration securityProps, URL overRideObjectGrid)
Parameters:
    attributes - Host and Port pair attributes which are tried in sequential order to connect. If an attempt to connect fails to one server, the next pair of host/port attribute is picked to re-try the connect.
    securityProps - Security configuration. It can be null if security is not configured.
    overRideObjectGrid - xml. This parameter can be null. If it is not null, the client side configuration of objectgrid plugin is overridden. Not all plugins can be overridden. For details please see the ObjectGrid documents


Returns:
     ClientClusterContext


Throws:
    com.ibm.websphere.objectgrid.ConnectException


connect

public ClientClusterContext connect(String clusterName,String host, String port, ClientSecurityConfiguration securityProps, URL overRideObjectGrid)
This allows client to connect to a Remote ObjectGrid The RemoteObject Grid is hosted as specified by the paramaters
Parameters:
    clusterName - The name of the cluster to which this client will attach iteself
    host - The host on which to connect to
    port - The clientAceess port which is listening.
    securityProps - Security configuration. It can be null if security is not configured
    overRideObjectGrid - xml. This parameter can be null. If it is not null, the client side configuration of objectgrid plugin is overridden. Not all plugins can be overridden. For details please see the ObjectGrid documents


Throws:
    com.ibm.websphere.objectgrid.ConnectException


getObjectGrid

public ObjectGrid getObjectGrid(ClientClusterContext context,String objectGridName)
Use this if a Remote ObjectGrid already exists. This method returns null if no ObjectGrid with this objectGridName exists
Parameters:
    context - A unique cluster context, with which the client needs to interact.
    objectGridName - the cached objectgrid name.


Returns:
     an ObjectGrid


getObjectGridAdministrator

public ObjectGridAdministrator getObjectGridAdministrator(ClientClusterContext context)
Return an ObjectGridAdministrator instance for this cluster. Each cluster will require the use of a different ObjectGridAdministrator.
Parameters:
    context - A unique cluster context, with which the client needs to interact.


Returns:
     an ObjectGrid


getCluster

public Cluster getCluster(String name)
Return Cluster instance
Parameters:
    name - Name of the cluster


Returns:
    


IBM WebSphere Extended Deployment (XD)TM
Release 6.0