com.j_spaces.core
Interface IJSpaceContainer

All Superinterfaces:

Remote

public interface IJSpaceContainer
extends Remote

GigaSpaces(tm) introduces a unique concept to the JavaSpaces world - Space Containers.
A Space Container is an entity that contains and manages spaces life cycle. A container may be used to create and destroy spaces on the fly. It is also responsible for registering the spaces both in the Jini Lookup Services and the RMI Registry Services in the environment. A Space Container is itself a Jini Service, and may be located through Jini lookup mechanisms. It is important to understand that the GigaSpaces(tm) Container is not the equivalent of a container in the EJB world.

For example, resource management is not the responsibility of the container, but of the spaces within the container.
This offers greater flexibility and scalability by allowing different spaces in the same container to have different threading schemes, indexing policies, etc.
Notice: each container must have a unique identifier name in the environment.

GigaSpaces includes built-in container, space, and cluster schema files. These are used when accessing the space and when running a clustered environment. In some cases, you may need to modify these to accommodate special options or when there is a need to tune the system behavior and performance. All schema files are located by default at \config\schemas. A factory-default is included as part of the gs-runtime.jar library under the config/schemas package. The configuration schemas are loaded through the classloader mechanism. This means that the order of the path by which a certain file will be allocated will be determined by the classpath. Notice: The schema files are always looked for by their name under a specific configuration package name config/schemas. This means the classpath should point to the directory containing the config directory and not the config directory itself. Since the gs-runtime.jar contains the factory defaults, the application need to put the customized configuration directory before the gs-runtime.jar in the application classpath. The container schema is defined through the schema attribute in the SpaceFinder URL in the following manner: ?schema= If a schema name is not defined, a default schema name called "default" is used. You can create a new container/space, on the fly, simply by using the following line of code: IJSpaceContainer containerProxy = (IJSpaceContainer)SpaceFinder.find("/./space-name"); This will create both the space and the container using the default schema. SpaceFinder.find("/./space-name?schema=persistent"); This will create a single persistent space (i.e., it will load the persistent-space-schema.xml file. The schema attribute is relevant only upon creation of spaces e.g. only with the Java protocol (java:// or /./).

Some spaces can reside in virtual memory only, while others can also be persistent. The server's architecture is highly modular and component driven. Special hooks, called "Connectors", are built into the architecture to enable tight integration with sophisticated applications/libraries. For example, the persistent backend of a persistent space is abstracted by an interface that may be implemented in a number of ways: over flat files, RDBMS, ODBMS, etc. The default communication protocol between a space and its proxies is an efficient, RMI-based messaging protocol (a special protocol was designed in order to minimize the round-trip time between the client and the server).

Every GigaSpaces(tm) container has an XML configuration file pointed to by a URL. This allows centric configuration file management. Most of the properties in the configuration file are optional and appropriate values are selected as defaults. GigaSpaces(tm) Server hosts a GigaSpaces(tm) Container instance. A GigaSpaces(tm) Container manages the life cycle of space instances. Life-cycle operations include: creation, destruction and moving a space from one container to another. The GigaSpaces(tm) Container is a remote object that implements the IJSpaceContainer interface. A GigaSpaces space is a SpaceImpl instance that implements the remote interface ISpaceInternal. Each space in a container has a unique name. This name can be used to reference a specific space after creation.

The container is also responsible for registering its GigaSpace instances in the environment's look up services and maintaining the leases it receives. It listens to new lookup services entering the environment and ensures that its GigaSpace instances are registered to these lookup services. The container maintains a map of the space names and attributes.

A container will create an automatically updated XML file (under in the GigaSpaces/config directory) that is self-maintained by the container - [ContainerName].XML. The contianer is responsible for hosting the spaces whose name appears in the container configuration file. Each space in the container may have different characteristics. Note that the default configuration of the container runs several Jini services (including Webster HTTPD, Reggie) embedded in the same JVM.

If you are planning to have an environment where Jini services are launched, or already have one, you are advised to disable these services. GigaSpaces can run multiple containers simultaneously on the same machine (each with its own JVM). ServiceBeanManager.getDiscardManager()

Since:

1.0

Version:

5.1

Author:

Igor Goldenberg

See Also:

IJSpace, SpaceFinder

Method Summary

IJSpace	createSpace(String spaceName, JSpaceAttributes spaceAttr) Deprecated.
void	destroySpace(String spaceName) Deprecated.
IJSpace	getClusteredSpace(String spaceName) Deprecated.
IJSpace	getClusteredSpace(String spaceName, boolean embedded) Deprecated. Use instead: getClusteredSpace(String)
String	getName() Returns the name of this container.
IJSpace	getSpace(String spaceName) Deprecated.
IJSpace	getSpace(String spaceName, boolean embedded) Deprecated. Use instead: getSpace(String)
JSpaceAttributes	getSpaceAttributes(String spaceName) Deprecated.
String[]	getSpaceNames() Deprecated.
SpaceURL	getURL() Returns the SpaceURL instance which was used to initialize the space.
boolean	isEmbedded() Checks if the container is embedded.
void	ping() Checks whether the container is alive and accessible.
void	shutdown() Deprecated.

Method Detail

createSpace

@Deprecated
IJSpace createSpace(String spaceName,
                               JSpaceAttributes spaceAttr)
                    throws CreateException,
                           RemoteException

Deprecated.

Creates a space with a unique name in this container and writes the created space to the appropriate Storage Adapter. If the specified space already exists in this container, CreateException will be thrown. The created space will be registered with all discovered Lookup Services in the network.

 // get proxy of container
 // containerUrl of the form: protocol://host:port/container-name 
 IJSpaceContainer containerProxy = (IJSpaceContainer)SpaceFinder.find(containerUrl);
 containerProxy.createSpace( spaceName, new JSpaceAttributes( null, null, false ) );
 

Parameters:

spaceName - the name of the space, which must be unique in this container

spaceAttr - Space attributes

Returns:

space proxy

Throws:

CreateException - This exception may be thrown if container failed to create space.

RemoteException - if a communication error occurs

destroySpace

@Deprecated
void destroySpace(String spaceName)
                  throws DestroyedFailedException,
                         RemoteException

Deprecated.

Destroys an existing space in this container, and unregisters it from all the Lookup Services.

 // ...after obtaining a containerProxy, either by createSpace(...)
 // or by IJSpace.getContainer()
 containerProxy.destroySpace( spaceName );
 

Parameters:

spaceName - the name of the space.

Throws:

DestroyedFailedException - This exception may be thrown if container failed to destroy space.

RemoteException - if a communication error occurs

getSpaceAttributes

@Deprecated
JSpaceAttributes getSpaceAttributes(String spaceName)
                                    throws NoSuchNameException,
                                           RemoteException

Deprecated.

Returns the JSpaceAttributes object of the specified space, through which you may access different space attributes.
i.e. General properties, Memory Usage, Lease Manager, Persistence, Cluster, Security, Caching, etc.

 JSpaceAttributes spaceAttr = containerProxy.getSpaceAttributes( spaceName );
 System.out.println("Space is private?: " + spaceAttr.m_isPrivate );
 System.out.println("Space is clustered?: " + spaceAttr.m_isClustered );
 

Parameters:

spaceName - the name of the space.

Returns:

the JSpaceAttributes object associated with the specified space.

Throws:

NoSuchNameException - if the specified space doesn't exist in this container.

RemoteException - if a communication error occurs

getSpaceNames

@Deprecated
String[] getSpaceNames()
                       throws RemoteException

Deprecated.

Returns the names of the spaces that belong to this container.

 // get all space names from container
 String[] names = containerProxy.getSpaceNames();
 for ( int i = 0; i < names.length; i++ )
    System.out.println( names[i] );
 
 

Returns:

String[] the names of the spaces that belong to this container.

Throws:

RemoteException - if a communication error occurs

getName

String getName()
               throws RemoteException

Returns the name of this container.

Returns:

the name of this container.

Throws:

RemoteException - if a communication error occurs

getSpace

@Deprecated
IJSpace getSpace(String spaceName,
                            boolean embedded)
                 throws NoSuchNameException,
                        RemoteException

Deprecated. Use instead: getSpace(String)

Returns a proxy of the specified space.

 IJSpaceContainer containerProxy = space.getContainer();
 containerProxy.getSpace( space.getName(), space.isEmbedded() );
 

Parameters:

spaceName - the name of the space.

embedded - If true and embedded (collocated) proxy is returned. Otherwise, a regular proxy (which contains a remote reference) is returned.

Returns:

IJSpace space proxy.

Throws:

NoSuchNameException - if the specified space does not exist in this container.

RemoteException - if a communication error occurs

getClusteredSpace

@Deprecated
IJSpace getClusteredSpace(String spaceName,
                                     boolean embedded)
                          throws NoSuchNameException,
                                 RemoteException

Deprecated. Use instead: getClusteredSpace(String)

Returns a clustered proxy of the specified space.

 // lets assume spaceUrl is of an embedded space. 
 // We would like to retrieve a remote reference to it.
 IJSpace collocatedProxy  = (IJSpace)SpaceFinder.find(spaceUrl);
 if (collocatedProxy.isEmbedded())
 {
    IJSpaceContainer container = collocatedProxy.getContainer();
    regularProxy = container.getClusteredSpace(collocatedProxy.getName(), false);
 }
 

Parameters:

spaceName - the name of the space.

embedded - If true and embedded (collocated) clustered proxy is returned. Otherwise, a regular clustered proxy (which contains a remote reference) is returned.

Returns:

IJSpace clustered space proxy.

Throws:

NoSuchNameException - if the specified space does not exist in this container.

RemoteException - if a communication error occurs

getSpace

@Deprecated
IJSpace getSpace(String spaceName)
                 throws NoSuchNameException,
                        RemoteException

Deprecated.

Returns a proxy of the specified space.

Parameters:

spaceName - the name of the space.

Returns:

IJSpace space proxy.

Throws:

NoSuchNameException - if the specified space does not exist in this container.

RemoteException - if a communication error occurs

getClusteredSpace

@Deprecated
IJSpace getClusteredSpace(String spaceName)
                          throws NoSuchNameException,
                                 RemoteException

Deprecated.

Returns a clustered proxy of the specified space.

Parameters:

spaceName - the name of the space.

Returns:

IJSpace clustered space proxy.

Throws:

NoSuchNameException - if the specified space does not exist in this container.

RemoteException - if a communication error occurs

shutdown

@Deprecated
void shutdown()
              throws RemoteException

Deprecated.

Shuts down this container. This also involves unregistering all registered spaces from Lookup services and closing connections to storage adapters.

Throws:

RemoteException - if a communication error occurs

isEmbedded

boolean isEmbedded()
                   throws RemoteException

Checks if the container is embedded.

Returns:

true if the container is embedded

Throws:

RemoteException - if a communication error occurs

getURL

SpaceURL getURL()
                throws RemoteException

Returns the SpaceURL instance which was used to initialize the space.

Notice: The SpaceURL object contains information on the space and container configuration/setup such as space url used, space/container/cluster schema used and other attributes.

The IJSpace keeps also its reference of the SpaceURL which launched the container.

Returns:

SpaceURL which initialized that specific space instance.

Throws:

RemoteException

ping

void ping()
          throws RemoteException

Checks whether the container is alive and accessible.

 IJSpaceContainer aContainer = (IJSpaceContainer)SpaceFinder.find("jini://lookup-host/container-name");
 try{
    aContainer.ping();
    System.out.println("Container alive");
 }
 catch (java.rmi.RemoteException re) {
    System.out.println("Container unreachable");
 }
 

Throws:

RemoteException - when container was unreachable