Using the Record Store Java Client

The Record Store Java Client package is intended to provide a working example of a client that communicates with a Record Store instance and issues record access requests. The sample client program is therefore a template that you can use as a basis for your own client program.

The Record Store API allows users to build client programs that invoke a Record Store instance to programmatically write records to and read records from the Record Store.

The Record Store API consists of two components:

The sample client package includes all the libraries needed to build clients. It also includes an Ant build script (that can compile and run the sample applications) as well as Eclipse .project and .classpath files for the sample client.

See the Oracle Technology Network for the Oracle Commerce CAS API Guide (which documents the Record Store API).

This topic describes the contents of the Record Store Java Client directory.

The Record Store Java Client has the following directory structure:

/recordstore-java-client
  /conf
  /lib
  /src
  .classpath
  .project
  build.xml
  run-sample-reader.bat
  run-sample-reader.sh
  run-sample-writer.bat
  run-sample-writer.sh

The contents are as follows:

The two Record Store sample client applications demonstrate the write and read functionality of the Record Store API.

The writer client (in the SampleWriter.java source file) performs the following actions:

  1. Creates a record that will be written to the Record Store.

  2. Makes a connection to a Record Store instance, assumed to reside on the localhost machine with a port of 8500.

  3. Starts a READ_WRITE transaction.

  4. Using the RecordStoreWriter methods, writes the record to the Record Store.

  5. Commits the write transaction.

The reader client (in the SampleReader.java source file) performs the following actions:

  1. Makes a connection to a Record Store instance, assumed to reside on the localhost machine with a port of 8500.

  2. Starts a READ transaction.

  3. Gets the ID of the last-committed generation.

  4. Using the RecordStoreReader.next() method, reads the record from the Record Store and then writes its contents to standard output.

  5. Commits the read transaction.

Note

If either application throws a RecordStoreFault exception, it is caught and the transaction is rolled back.

The Ant build.xml file can compile and run the sample writer client program.

The file has the following targets:

To run the sample writer client with the Ant build script:

  1. Start the CAS Service if it is not already running.

  2. From a command prompt, navigate to the recordstore-java-client directory and issue the following command to compile and run the sample writer client demo: 

    run-sample-writer

The sample writer client’s output messages should be similar to this example: 

Buildfile: build.xml

init:
  [mkdir] Created dir: C:\Endeca\CAS\<version>\sample\recordstore-java-client\build

compile:
  [javac] Compiling 2 source files to C:\Endeca\CAS\<version>\sample\recordstore-java-client\build

run-sample-writer:
  [java] Setting record store configuration ...
  [java] Starting a new transaction ...
  [java] Writing records ...
  [java] Committing transaction ...
  [java] DONE

BUILD SUCCESSFUL
Total time: 14 seconds

You can use the -c (count) option with the read-baseline task of the Record Store Command-line Utility to determine if the Record Store has any records: 

C:\Endeca\CAS\<version>\bin> recordstore-cmd.bat read-baseline -a rs1 -c 
Records read: 1

As the example shows, the Record Store has the one record that was read in by the sample writer client.

The Ant build.xml file can compile and run the sample reader client program.

The file has the following targets:

To run the sample reader client with the Ant build script:

  1. Start the CAS Service if it is not already running.

  2. From a command prompt, navigate to the recordstore-java-client directory and issue the following command to compile and run the sample reader client demo: 

    run-sample-reader

The sample reader client’s output messages should be similar to this example:

Buildfile: build.xml

init:

compile:

run-sample-reader:
  [java] Starting a new transaction ...
  [java] Getting the last committed generation ...
  [java] Reading records ...
  [java]   RECORD: [Endeca.FileSystem.Path=id1, property.name=property.value]
  [java] 1 record(s) read
  [java] Committing transaction ...
  [java] DONE

BUILD SUCCESSFUL
Total time: 8 seconds

As the example output shows, the properties of the record in the Record Store are written out.

If you use Eclipse for your projects, the sample client package includes Eclipse .project and .classpath files.

As a prerequisite, make sure that you have run the Ant build file with at least the compile target. This will generate the necessary Web service stubs.

To load the sample client project:

  1. Start Eclipse.

  2. Import the project:

    1. Open the File menu.

    2. Click Import...

    3. Expand the General folder.

    4. Select Existing Projects into Workspace

    5. Select the recordstore-java-client project.

    6. Click Finish.

This section provides an overview of the more important operations of the sample writer client program. You can modify the files and add other Record Store operations.

The methods for these operations are described in the CAS API Guide, and in the Record Store Javadocs.

Assuming that you have opened the SampleWriter.java source in Eclipse or another editor, you should note the following important operations:

  1. A constant is set for the value of the idPropertyName configuration property that is used for the Record Store instance. 

    public static final String PROPERTY_ID = "Endeca.FileSystem.Path";

  2. After a LinkedList of Record objects is instantiated, a record is created and added to the list. The Record.addPropertyValue() method is used to add the property values to the record. 

    Collection<Record> records = new LinkedList<Record>();
Record record = new Record();
record.addPropertyValue(new PropertyValue(PROPERTY_ID, "id1"));
record.addPropertyValue(new PropertyValue("property.name",
   "property.value"));
records.add(record);

  3. Using the RecordStoreLocator utility class, create a Web service locator with host name, port number, and Record Store instance name: 

    RecordStoreLocator locator = RecordStoreLocator.create("localhost", 8500, recordStoreInstance);

  4. Use the RecordStore.getRecordStore() method to establish a connection to the Record Store instance: 

    RecordStore recordStore = locator.getRecordStore();

  5. Using the transaction ID created by the RecordStore.startTransaction() method, the RecordStoreWriter.createWriter() method is used to create a writer. 

    tId = recordStore.startTransaction(TransactionType.READ_WRITE);

RecordStoreWriter writer =
   RecordStoreWriter.createWriter(recordStore, tId);

  6. The writer first writes a "Delete All" record, then writes the sample record, and finally closes the writer. 

    writer.deleteAll();
writer.write(records);
writer.close();

  7. The RecordStore.commitTransaction() method closes the transaction. 

    recordStore.commitTransaction(tId);

Note

If a RecordStoreFault exception occurs during the write process, it is caught and the RecordStore.rollbackTransaction() method rolls back the READ_WRITE transaction.

This section provides an overview of the more important operations of the sample reader client program. You can modify the files and add other Record Store operations.

The methods for these operations are described in theCAS API Guide and in the Record Store API Reference (Javadoc).

The SampleReader.java source program executes the following important operations:

  1. Using the RecordStoreLocator utility class, create a Web service locator with host name, port number, and Record Store instance name: 

    RecordStoreLocator locator = RecordStoreLocator.create("localhost", 8500, recordStoreInstance);

  2. Use the RecordStore.getRecordStore() method to establish a connection to the Record Store instance: 

    RecordStore recordStore = locator.getRecordStore();

  3. Using the transaction ID created by the RecordStore.startTransaction() method, the RecordStore.getLastCommittedGenerationId() method is used to get the ID of the last-committed generation in the Record Store. 

    tId = recordStore.startTransaction(TransactionType.READ);

GenerationId gId = recordStore.getLastCommittedGenerationId(tId);

  4. The RecordStoreReader.createBaselineReader() method uses the transaction ID and the generation ID to create a reader. 

    RecordStoreReader reader =
   RecordStoreReader.createBaselineReader(recordStore, tId, gId);

  5. Within a while loop, the RecordStoreReader hasNext() and next() methods are used to read the sample record. The reader is closed when there are no more records to be read. 

    int count = 0;
while (reader.hasNext()) {
   Record record = reader.next();
   System.out.println("  RECORD: " + record);
   count++;
}
reader.close();

  6. The RecordStore.commitTransaction() method closes the transaction. 

    recordStore.commitTransaction(tId);

Note

As with the writer client, if a RecordStoreFault exception occurs during the read process, it is caught and the RecordStore.rollbackTransaction() method rolls back the READ transaction.

Copyright © Legal Notices