Summary: When persisting into a relational database, GigaSpaces uses two configuration files: type.properties and jdbc.properties.

Overview

When persisting into a relational database, GigaSpaces uses two configuration files:

  • The type.properties file includes the Java-to-SQL mapping definition. This information is essential, since various RDBMS have different internal names for column-types, and this information is not always available dynamically from their metadata.
  • The jdbc.properties file includes information about the driver class, URL, and authentication information that the JDBC driver uses to connect to the RDBMS.

GigaSpaces queries the JDBC driver in runtime for type-mapping information. Each JDBC Driver may have different Java to SQL mapping.

In some cases, you can override these default setting to optimize the database storage mode.

To override the default JDBC mapping, you can assign values in the types.properties file. In many cases, there are a number of options to map a type (for example, binary type). You should consult the RDBMS manuals and choose the optimal type.

JDBC SA Configuration File Location

The location of the JDBC SA configuration files should be defined when creating a persistent space. GigaSpaces distribution includes configuration files for all major RDBMS vendors. These are located at the <GigaSpaces Root>\GenericJDBCProperties folder.

To make sure GigaSpaces uses the pre-defined configuration file, make sure the space schema file you are using includes the following:

<StorageAdapterURL>/GenericJDBCProperties/HSQLProperties</StorageAdapterURL>

The space instance searches for these files via a resource bundle search mechanism - i.e. you should make sure <GigaSpaces Root> is part of the GigaSpaces space JVM classpath.

You can place the JDBC SA configuration files at your preferred location. You should make sure the relevant folder is part of the space JVM classpath or application classpath when running in embedded space mode.

Overriding GenericJDBCProperties

When starting two or more persistent spaces on the same machine with an embedded database (like HSQL), you might need to override the GS_INSTALL_DIR or GenericJDBCProperties, otherwise all spaces can load the same GenericJDBCProperties/HSQLProperties/jdbc.properties files, which can result in failure when creating the database.

Using the SpaceFinder properties object, you can override the connectionUrl property, override the username and password, or any other jdbc.properties property in runtime:

/** Override /GenericJDBCProperties/HSQLProperties/jdbc.properties */
Properties prop = new Properties();
prop.setProperty("driverClass", "org.hsqldb.jdbcDriver");
prop.setProperty("connectionUrl", "jdbc:hsqldb:/home/igor/GigaSpacesXAP6.0/db-files/primarySpaceDB");
prop.setProperty("username", "igor");
prop.setProperty("password", "giga");
IJSpace space = (IJSpace)SpaceFinder.find("/./myHSQLSpace", prop);

Persisting Binary Fields

Any field that its type is not a simple type (e.g custom Java objects, arrays) is persisted as a binary field. The type of this field is defined using the binary property in the types.properties file.

For example: binary=LONG means that a LONG database type is used for binary fields.

The longBinary property is intended for persisting internal space tables. Make sure you do not confuse this property with the binary property described above.

Persisting large objects is done using BLOBS (Binary Large OBjects). For more details, refer to the Persisting Large Entries section.

Example

You can download the hsqlpersistent-space-schema.xml schema to be used as part of this example. This file should be copied into <GigaSpaces Root>\config\schemas.

If you are using GigaSpaces version 6.0.1 and onwards, remove the min_connections, max_connections, and port elements from the schema, since they are not used in this version.

The HSQL database jdbc.properties file:

driverClass=org.hsqldb.jdbcDriver
#embedded mode
connectionUrl=jdbc:hsqldb:testDB
#remote mode
#connectionUrl=jdbc:hsqldb:hsql://localhost
username= sa
password=

The name and location of the HSQL database files is determined by the jdbc.properties file. In this case the HSQL database files are created in the <GigaSpaces Root\bin folder and named testDB.*.

You can override properties in the jdbc.properties file using the SpaceFinder, see above.

Property Description
driverClass The JDBC driver class – org.hsqldb.jdbcDriver. This class is located in the hsqldb.jar file in the <GigaSpaces ROOT>/lib/jdbc directory. The jar file is already included in the GigaSpaces classpath, so there is no need to add it manually.
connectionUrl The connectionUrl is the URL used by the JDBC driver to establish a connection to the database. You may replace the testDB with your own database name.
username Database user username.
password Database user password.

The HSQL database types.properties file:

java.lang.String=VARCHAR(3000)
java.lang.Boolean=
java.lang.Byte=
java.lang.Short=
java.lang.Integer=
java.lang.Long=
java.lang.Float=
java.lang.Double=
java.lang.Character=
binary=VARBINARY
longBinary=LONGVARBINARY

The space schema should include the following as part of the <persistent> options:

<persistent>
   <enabled>true</enabled>
   <StorageAdapterClass>com.j_spaces.sadapter.GenericJDBC.JDBCStorageAdapter</StorageAdapterClass>
   <AdapterType />
   <DataBaseName>${com.gs.home}/GenericJDBCProperties/HSQLProperties/mydb</DataBaseName>
   <userName />
   <password />
   <Number_Sync_Objects>100</Number_Sync_Objects>
   <Check_Point_Period>1000</Check_Point_Period>
   <Page_Pool_Size>32768</Page_Pool_Size>
   <Sync_On_Commit>true</Sync_On_Commit>
   <StorageAdapterURL>/GenericJDBCProperties/HSQLProperties</StorageAdapterURL>
   <force-cold-init>false</force-cold-init>
</persistent>

It is possible to use a different adapter according to your database. To do this, in the <DataBaseName> tag, specify an adapter instead of HSQLProperties. The following adapters are available under <GigaSpaces Root>\GenericJDBCProperties:

  • CacheProperties
  • DB2Properties
  • DefaultProperties
  • HSQLProperties
  • MSSQLProperties
  • MySQLProperties
  • OracleProperties
  • PointBaseProperties
  • PostgreSQLProperties
  • SybaseiAnywhereProperties

All of the schema elements above can be overridden using a custom properties file. For more details, see: Overriding Default Configuration.

To start a persistent space use:

gsInstance "/./hsqlspace?schema=persistent"

The mappings for wrapper classes (Boolean, Byte, etc.) are determined from the driver's metadata during runtime. Strings and longBinary data are mapped explicitly.
GigaSpaces maps native Java types into their relevant SQL types. Arrays, Collections, and user-defined class type attributes are serialized and stored as a blob inside a relevant row cell. If your Entry holds large arrays or collection attributes, make sure your types.properties includes sufficient size for a blob SQL type.
The database table that stores Entry data is generated when the first instance of a specific class is written to the space. A Javaspace.snapshot call also generates a relevant empty table.
The database tables generated by GigaSpaces are deleted when cleaning the space. This can be done by calling the IJSpace.clean API , running the space clean - GigaSpaces CLI command line, or by running the clean space option in the Space Browser.

GigaSpaces.com - Legal Notice - 3rd Party Licenses - Site Map - API Docs - Forum - Downloads - Blog - White Papers - Contact Tech Writing - Gen. by Atlassian Confluence