The Space URL

Introduction

In order to locate a space you should specify its URL. The URL is used as part of the SpaceFinder.find API , Cache API , cluster configuration , JMS configuration , JCA configuration, JDBC configuration , space browser and utilities, and all GigaSpaces C++,.Net and Java examples.

The general format of the space URL is:

<protocol>://<host name>:<port>/<container name>/<space name>?<properties>

 

Name

Description

Protocol

[ RMI | Jini | JAVA ]

Jini - Remote access using Jini for lookup

RMI - Remote access using RMI registry for lookup

Java - local embedded access

Host name/IP

The machine host name/IP running the space container. May be when Jini is used as a protocol. In this case the space is located using multicast or unicast with search path.

Port

The RMI Registry or Jini lookup port. If no port is specified, then the default port will be used

Container Name

The name of the container that holds the space. May be '*' when Jini is used as a protocol. In this case the container will be ignored when performing lookup and the space will be searched regardless of the container that holds it.

Space Name

The space name to search. The same name defined when space has been created via the Space browser or the createSpace utility.

Properties String

(Optional) named value list of special properties

 

URL Properties

The following are optional Property String values.

These Strings are defined within the com.j_spaces.core.client.SpaceURL class as static attributes.

 

Property name

Property string

Description

Optional values

ANY

*

Used with Jini protocol to indicate any host or container name

 

CLUSTER_PROXY

Cluster

Used to locate clustered space. Default is non clustered.

Example: ws://[http-host:8087]/containerName/JavaSpaces?cluster=true

Cluster name

CREATE

create

Creates a new space using the container's default parameters. New spaces use the default space configuration file.

Example: java://localhost:10098/containerName/JavaSpaces?create=true

 

DESTROY

Destroy

Destroys an existing space inside the container.

Example: java://localhost:10098/containerName/JavaSpaces?destroy=true

 

EMBEDDED_NOT_CACHE_MODE

noCache

When noCache=true, a new instance of  the Container is initialized at each SpaceFinder.find() invocation. This allows you to run multiple container instances in one JVM. When noCache=false, a singleton Container is returned.

 

EMBEDDED_SPACE_PROTOCOL

java:

Start the space in local embedded mode. Make sure you have the com.gs.home JVM property defined to specify the space configuration file directory

 

FIFO_MODE

fifo

Indicates that all take/write operations be conducted in FIFO mode. Default is false. Example: jini://localhost:10098/containerName/JavaSpaces?fifo=true

true | false

GROUPS

groups

The Jini lookup service group to find container or space using multicast.

Example: jini://*/containerName/spaceName?groups=grid

Group name

JINI_PROTOCOL

jini:
 

Using JINI Lookup service to search for the space

 

LOCAL_CACHE_UPDATE_MODE

updateMode

Push or pull update mode. Example: jini://localhost:10098/containerName/JavaSpaces?useLocalCache&updateMode=1

UPDATE_MODE_PULL = 1 UPDATE_MODE_PUSH = 2

RMI_PROTOCOL

rmi:

Using RMI Lookup service to search for the space

 

SECURITY_MANAGER

securityManager

When false, SpaceFinder will not initialize RMI security manager. Default is true. Example: jini://localhost:10098/containerName/JavaSpaces?securityManager=false

 

TIMEOUT

Timeout

The max timeout in ms to find a Container or Space using multicast jini:// protocol. Default: 60000ms

Example: jini://<code>*</code>/containerName/JavaSpaces?timeout=10000

 

USE_LOCAL_CACHE

useLocalCache

Turn Master-Local Space mode.

By default Master-Local mode is turned off. To enable master local have the useLocalCache as part of the URL

 

VERSIONED

versioned

When false, Optimistic lock is disabled. Default is true.

Example: jini://localhost:10098/containerName/JavaSpaces?versioned=false

 

CLUSTER_NAME

clustername

The cluster name to lookup using multicast. The returned object is a clustered proxy.

 

CLUSTER_GROUP

clustergroup

The cluster group to lookup using multicast. The returned object is a clustered proxy.

 

PROPERTIES_FILE_NAME

properties

if properties property is used as part of the URL space, space and container schema will be loaded and the properties listed as part of the properties file ([prop-file-name].properties ) will be used to resolve the relevant space and container configuration properties. The property URL can be used also to load system properties while JVM starts.

 

 

Example for space URL using Space URL options:

jini://*/*/mySpace?useLocalCache&versioned=false

/./mySpace?cluster_schema=partitioned&total_members=4&id=1

 

Examples of Space The Space URL

Accessing remote space using RMI Registry in a specific host and container name

·         RMI://mycontainerhost/mycontaineraname/myspace

   With this option, the host must be specified along with the container name and space name. By default, the container name is set to be the same as the container host name.

Accessing remote space using Jini Lookup service - Unicast discovery

·         JINI://mylookuphost/mycontainername/myspace

·         JINI://hostname/*/myspace

Accessing remote space using the Jini Lookup service – multicast discovery

·         JINI://*/mycontainername/myspace

·         JINI://*/*/myspace

Accessing remote container

The following return com.j_spaces.core.IJSpaceContainer that allows accessing/creating/destroying spaces.

·         RMI://mycontainerhost/mycontaineraname

·         JINI://mylookuphost/mycontainername

·         JINI://*/mycontainername

Starting embedded space using the Java Protocol

·         JAVA://containerHostName:port/myContainerName/spaceName

Locating Spaces in a Cluster

When accessing a space that is part of a cluster, the cluster configuration is loaded into the client side the first time you access the space. Therefore, all load-balancing/failover occurs transparently. The same goes for the replication - the space receives all its replication configurations from its cluster schema settings. See below URL examples for accessing clustered space:

·         jini://<host>/*/*?clustername=ClusterName

·         jini://<host>/*/*?clustername=ClusterName&clustergroup=GroupName

 

These URLs are uncoupled from a specific container or space name (the ‘*' is a Wildcard replacement). The clustergroup parameter may be used to limit the search to a specific failover group.

 

For example, to find a proxy in cluster C using Jini multicast Lookup Service when the search for the Lookup Service done using multicast, use the following URL:

jini://*/*/*?clustername=C

 

You may also construct a URL that is based on multiple spaces URL separated by semi colon - ";". The client will access the first available space where the search order is based on the URLs order:

rmi://host1/container1/space1;rmi://host2/container2/space2;rmi://host3/container3/space3

 

Running Replicated Cache

To start three space instances using the replicated cache topology  , which enables replicating their data and operations synchronously, you should have the following commands:

Member 1

gsServer "/./myCache?cluster_schema=sync_replicated&total_members=3&id=1"

Member 2

gsServer "/./myCache?cluster_schema=sync_replicated&total_members=3&id=2"

Member 3

gsServer "/./myCache?cluster_schema=sync_replicated&total_members=3&id=3"

 

To access the replicated space, the client application should have the following call:

JavaSpaces API:

IJSpace space =

(IJSpace)SpaceFinder.find("jini://*/./mySpace");

 

Map API:

IMap cache =

(IMap)CacheFinder.find("jini://*/./myCache");

 

Running Partitioned Cache

To start three space instances using the partitioned cache topology where each partition stores different portions of the data, you should have the following calls:

Member 1

gsServer "/./myCache?cluster_schema=partitioned&total_members=3&id=1"

Member 2

gsServer "/./myCache?cluster_schema=partitioned&total_members=3&id=2"

Member 3

gsServer "/./myCache?cluster_schema=partitioned&total_members=3&id=3"

 

To access the partitioned space, the client application should have the following call:

JavaSpaces API:

IJSpace space =

(IJSpace)SpaceFinder.find("jini://*/./mySpace");

 

Map API:

IMap cache =

(IMap)CacheFinder.find("jini://*/./myCache");

 

Running Embedded Cache

You may run the replicated or partitioned space from within your application. In this case, the space instance will be running in the same memory address as the application - i.e. embedded space. See the following example for running three space instances in partitioned embedded mode.

Each CacheFinder.find() or SpaceFinder.find() call should be done from a different application process.

JavaSpaces API:

Member1

IJSpace space =

(IJSpace)SpaceFinder.find("/./mySpace?schema=cache&cluster_schema=partitioned&total_members=3&id=1");

Member 2

IJSpace space =

(IJSpace)SpaceFinder.find("/./mySpace?schema=cache&cluster_schema=partitioned&total_members=3&id=2");

Member 3

IMap space =

(IJSpace)SpaceFinder.find("/./mySpace?schema=cache&cluster_schema=partitioned&total_members=3&id=3");

 

Map API:

Member1

IMap cache =

(IMap)CacheFinder.find("/./myCache?schema=cache&cluster_schema=partitioned&total_members=3&id=1");

Member 2

IMap cache =

(IMap)CacheFinder.find("/./myCache?schema=cache&cluster_schema=partitioned&total_members=3&id=2");

Member 3

IMap cache =

(IMap)CacheFinder.find("/./myCache?schema=cache&cluster_schema=partitioned&total_members=3&id=3");

 

Running Master-Local Cache

To start a local cache instance using the Master-Local topology, the client should provide the space URL where the URL can represent a clustered space (replication or partitioned) together with the useLocalCache property, as in the following example:

JavaSpaces API:

IJSpace cache = (IJSpace)SpaceFinder.find("jini://*/./mySpace?useLocalCache")

 

Map API:

IMap cache = (IMap)CacheFinder.find("jini://*/./myCache?useLocalCache")