Overview
A Space is a logical in-memory service, which can store entries of information. An entry is a domain object; In Java, an entry can be as simple a POJO or a SpaceDocument.
When a client connects to a space, a proxy is created that holds a connection which implements the space API. All client interaction is performed through this proxy.
The space is accessed via a programmatic interface which supports the following main functions:
- Write - the semantics of writing a new entry of information into the space.
- Read - read the contents of a stored entry into the client side.
- Take - get the value from the space and delete its content.
- Notify - alert when the contents of an entry of interest have registered changes.
Embedded Space
A client communicating with a an embedded space performs all its operation via local connection. There is no network overhead when using this approach.
Here is an example how to create an embedded space. The EmbeddedSpaceConfigurer
is used to configure the space url:
GigaSpace gigaSpace = new GigaSpaceConfigurer(new EmbeddedSpaceConfigurer("mySpace")).gigaSpace();
<os-core:embedded-space id="space" space-name="mySpace"/>
<os-core:giga-space id="gigaSpace" space="space"/>
<bean id="space" class="org.openspaces.core.space.EmbeddedSpaceFactoryBean">
<property name="name" value="space" />
</bean>
<bean id="gigaSpace" class="org.openspaces.core.GigaSpaceFactoryBean">
<property name="space" ref="space" />
</bean>
The Embedded space can be used in a distributed architecture such as the replicated or partitioned clustered space:
A simple way to use the embedded space in a clustered architecture would be by deploying a clustered space or packaging your application as a Processing Unit and deploy it using the relevant SLA.
Remote Space
A client communicating with a remote space performs all its operation via a remote connection. The remote space can be partitioned (with or without backups) or replicated (sync or async replication based).
Here is an example how a client application can create a proxy to interacting with a remote space:
GigaSpace gigaSpace = new GigaSpaceConfigurer(new SpaceProxyConfigurer("mySpace")).gigaSpace();
<os-core:space-proxy id="space" space-name="mySpace"/>
<os-core:giga-space id="gigaSpace" space="space"/>
<bean id="space" class="org.openspaces.core.space.SpaceProxyFactoryBean">
<property name="name" value="space" />
</bean>
<bean id="gigaSpace" class="org.openspaces.core.GigaSpaceFactoryBean">
<property name="space" ref="space" />
</bean>
A full description of the Space URL Properties can be found here.
Reconnection
When working with a remote space, the space may become unavailable (network problems, processing unit relocation, etc.). For information on how such disruptions are handled and configured refer to Proxy Connectivity.
Local Cache
XAP supports a Local Cache (near cache) configuration. This provides a front-end client side cache that will be used with the read
operations implicitly . The local cache will be loaded on demand or when you perform a read
operation and will be updated implicitly by the space.
Here is an example for a GigaSpace
construct with a local cache:
// Initialize remote space configurer:
SpaceProxyConfigurer urlConfigurer = new SpaceProxyConfigurer("space");
// Initialize local cache configurer
LocalCacheSpaceConfigurer localCacheConfigurer = new LocalCacheSpaceConfigurer(urlConfigurer);
// Create local cache:
GigaSpace localCache = new GigaSpaceConfigurer(localCacheConfigurer).gigaSpace();
<os-core:space-proxy id="space" space-name="mySpace"/>
<os-core:local-cache id="localCacheSpace" space="space"/>
<os-core:giga-space id="localCache" space="localCacheSpace"/>
<bean id="space" class="org.openspaces.core.space.SpaceProxyFactoryBean">
<property name="name" value="space" />
</bean>
<bean id="localCacheSpace"
class="org.openspaces.core.space.cache.LocalCacheSpaceFactoryBean">
<property name="space" ref="space" />
</bean>
Local View
XAP supports a Local View configuration. This provides a front-end client side cache that will be used with any read
or readMultiple
operations implicitly. The local view will be loaded on start and will be updated implicitly by the space.
Here is an example for a GigaSpace
construct with a local cache:
// Initialize remote space configurer:
SpaceProxyConfigurer configurer = new SpaceProxyConfigurer("space");
// Initialize local view configurer
LocalViewSpaceConfigurer localViewConfigurer = new LocalViewSpaceConfigurer(configurer)
.addViewQuery(new SQLQuery<Message>(Message.class, "processed = true"))
.addViewQuery(new SQLQuery<Message>(Message.class, "priority > 3"));
// Create local view:
GigaSpace localView = new GigaSpaceConfigurer(localViewConfigurer).gigaSpace();
<os-core:space-proxy id="space" space-name="mySpace" />
<os-core:local-view id="localViewSpace" space="space">
<os-core:view-query class="Message" where="processed = true"/>
<os-core:view-query class="Message" where="priority > 3"/>
</os-core:local-view>
<os-core:giga-space id="localView" space="localViewSpace"/>
<bean id="space" class="org.openspaces.core.space.SpaceProxyFactoryBean">
<property name="name" value="space" />
</bean>
<bean id="viewSpace" class="org.openspaces.core.space.cache.LocalViewSpaceFactoryBean">
<property name="space" ref="space" />
<property name="localViews">
<list>
<bean class="com.j_spaces.core.client.view.View">
<constructor-arg index="0" value="com.example.Message1" />
<constructor-arg index="1" value="processed = true" />
</bean>
<bean class="com.j_spaces.core.client.view.View">
<constructor-arg index="0" value="com.example.Message2" />
<constructor-arg index="1" value="priority > 3" />
</bean>
</list>
</property>
</bean>
Resource cleanup
There are two types of resources associated with Space instances and Space clients that need to be freed up before shutting down your application.
Thread and memory resources
If your space client or embedded space are running within a Spring-enabled environment (e.g. the XAP service grid or a standalone Spring application), and are configured in a Spring application context, these resources will be cleaned up automatically when the Spring application context is destroyed.
However, if you start the space client or space instance programmatically, you must call the UrlSpaceConfigurer destroy()
method when your application no longer uses the space instance / space client.
Example:
SpaceProxyConfigurer urlConfigurer = new SpaceProxyConfigurer("space");
//....
urlConfigurer.destroy();
// Local cache
LocalCacheSpaceConfigurer localCacheConfigurer = new LocalCacheSpaceConfigurer(urlConfigurer);
localCacheConfigurer.destroy();
// Local view
LocalViewSpaceConfigurer localViewConfigurer = new LocalViewSpaceConfigurer(urlConfigurer);
localViewConfigurer.destroy();
When using LocalCache and LocalView you need to call the destroy()
method on their respective configurer.
Communication resources
All communication related resources in XAP are shared between all the XAP components at the Java classloader level. If you’re using the GigasSpaces service grid to run your XAP application you do not need to handle communication resources cleanup explicitly. If your application runs in a standalone environment or another hosted environment (e.g. a JEE application server) you will need to explicitly clean up those resources. You need to shutdown these resources explicitly when your application no longer uses the XAP components (e.g. when it’s un deployed from the application server). This is done by calling the static shutdown() method on the LRMIManager. Note that if the JVM process is shut down anyway, you do not need to do explicitly shut down the communication resources.
Example:
SpaceProxyConfigurer urlConfigurer = new SpaceProxyConfigurer("space");
//....
urlConfigurer.destroy();
LRMIManager.shutdown();
Security
A secured space should be configured with a security context so that it can be accessed (when connecting to it remotely). Here is an example of how this can be configured:
<os-core:space-proxy id="space" space-name="mySpace">
<os-core:security username="sa" password="adaw@##$" />
</os-core:space-proxy>
<bean id="space" class="org.openspaces.core.space.SpaceProxyFactoryBean">
<property name="name" value="space" />
<property name="securityConfig">
<bean class="org.openspaces.core.space.SecurityConfig">
<property name="username" value="sa" />
<property name="password" value="adaw@##$" />
</bean>
</property>
</bean>
Here is an example of how to define security with an embedded space. In this case, we enable security and specify the username and password.
<os-core:space-proxy id="space" space-name="mySpace">
<os-core:security username="sa" password="adaw@##$" />
</os-core:space-proxy>
<bean id="space" class="org.openspaces.core.space.EmbeddedSpaceFactoryBean">
<property name="name" value="space" />
<property name="securityConfig">
<bean class="org.openspaces.core.space.SecurityConfig">
<property name="username" value="sa" />
<property name="password" value="adaw@##$" />
</bean>
</property>
</bean>
It is possible to configure the space to be secured using deploy time properties (bean level properties), without declaring the security element. The security.username
and security.password
can be provided, and the spaces defined within the processing unit are automatically secured.
Persistency
When constructing a space, it is possible to provide Space Persistency extensions using Spring-based configuration (instead of using the space schema). Here is an example of how it can be defined:
<bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
<property name="driverClassName" value="org.hsqldb.jdbcDriver"/>
<property name="url" value="jdbc:hsqldb:hsql://localhost:9001"/>
<property name="username" value="sa"/>
<property name="password" value=""/>
</bean>
<bean id="sessionFactory" class="org.springframework.orm.hibernate3.LocalSessionFactoryBean">
<property name="dataSource" ref="dataSource"/>
<property name="mappingResources">
<list>
<value>Person.hbm.xml</value>
</list>
</property>
<property name="hibernateProperties">
<props>
<prop key="hibernate.dialect">org.hibernate.dialect.HSQLDialect</prop>
<prop key="hibernate.cache.provider_class">org.hibernate.cache.NoCacheProvider</prop>
<prop key="hibernate.cache.use_second_level_cache">false</prop>
<prop key="hibernate.cache.use_query_cache">false</prop>
<prop key="hibernate.hbm2ddl.auto">update</prop>
</props>
</property>
</bean>
<bean id="hibernateSpaceDataSource" class="com.gigaspaces.datasource.hibernate.DefaultHibernateSpaceDataSource">
<property name="sessionFactory" ref="sessionFactory"/>
</bean>
<os-core:embedded-space id="space" space-name="mySpace" schema="persistent" space-data-source="hibernateSpaceDataSource" />
<bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
<property name="driverClassName" value="org.hsqldb.jdbcDriver"/>
<property name="url" value="jdbc:hsqldb:hsql://localhost:9001"/>
<property name="username" value="sa"/>
<property name="password" value=""/>
</bean>
<bean id="sessionFactory" class="org.springframework.orm.hibernate3.LocalSessionFactoryBean">
<property name="dataSource" ref="dataSource"/>
<property name="mappingResources">
<list>
<value>Person.hbm.xml</value>
</list>
</property>
<property name="hibernateProperties">
<props>
<prop key="hibernate.dialect">org.hibernate.dialect.HSQLDialect</prop>
<prop key="hibernate.cache.provider_class">org.hibernate.cache.NoCacheProvider</prop>
<prop key="hibernate.cache.use_second_level_cache">false</prop>
<prop key="hibernate.cache.use_query_cache">false</prop>
<prop key="hibernate.hbm2ddl.auto">update</prop>
</props>
</property>
</bean>
<bean id="hibernateSpaceDataSource" class="com.gigaspaces.datasource.hibernate.DefaultHibernateSpaceDataSource">
<property name="sessionFactory" ref="sessionFactory"/>
</bean>
<bean id="space" class="org.openspaces.core.space.EmbeddedSpaceFactoryBean">
<property name="name" value="space" />
<property name="schema" value="persistent" />
<property name="spaceDataSource" ref="hibernateSpaceDataSource" />
</bean>
The above example uses Spring built-in support for configuring both a custom JDBC DataSource
and a Hibernate SessionFactory
to define and use the GigaSpaces built-in HibernateSpaceDataSource
. The GigaSpaces data source is then injected into the space construction (note the specific schema change), and causes the space to use it.
This configuration can also be used with the XAP Mirror Service deployed as a Processing Unit.