Quick Reference for Java Persister Classes

Persister.Persister() is used to write data to the extent of an ObjectScript persistent class. A SchemaManager provides the connection to the target extent and interfaces with the Schema Registry on the server.

Persister (SchemaManager schemaManager, RecordSchema schema, int indexMode) throws PersisterException
Persister (SchemaManager schemaManager, RecordSchema schema, int indexMode, int bufferSize) throws PersisterException

parameter:

• schemaManager — a local instance of SchemaManager connected to the Schema Registry on the server.

• schema — a schema (either a JSON string or a RecordSchema) describing the target extent on the server.

• indexMode — valid values are attributes INDEX_MODE_DEFAULT (= -1), INDEX_MODE_DEFERRED (= 0), or INDEX_MODE_IMMEDIATE (= 2).

• bufferSize — optional buffer size. Defaults to attribute DEFAULT_BUFFER_SIZE (= 32_000)

Persister.add() adds one or more records to a buffer. If adding a record causes the buffer to overflow then the buffer automatically flushes to the server. Persister.flush()Opens in a new tab may be used to write a partially filled buffer.

Local buffers are presumed to be thread-private as there are no concurrency guarantees with local buffers.

add ( record )

serializes and adds one or more Record objects to the buffer.

synchronized void  add (Record record)
synchronized< R extends Record > void  add (R[] records)

• record — the Record object to be added to the buffer

• records — array of Record objects to be added to the buffer

add ( list )

adds one or more serialized ListWriter records to the buffer.

synchronized void  add (ListWriter vList)
synchronized void  add (ListWriter[] lists)

• vList — serialized ListWriter object to be added to the buffer

• lists — array of ListWriter objects to be added to the buffer

add ( list, localBuffer )

adds one or more serialized ListWriter records to the specified local buffer.

void  add (ListWriter serial, PersisterBuffer localBuffer)
synchronized void  add (ListWriter[] lists, PersisterBuffer localBuffer)

• serial — serialized ListWriter object

• lists — array of serialized ListWriter objects

• localBuffer — local buffer where serialized value is to be added

Persister.close() close this instance of Persister.

void  close ()

Persister.createLocalBuffer() creates an instance of PersisterBuffer that is expected to be used within a thread and not shared with any other threads as there are no built in concurrency controls. If bufferQueue is specified, filled buffers will be placed in the buffer queue instead of being written directly to the server.

PersisterBuffer  createLocalBuffer ()
PersisterBuffer  createLocalBuffer (LinkedBlockingQueue< BufferWrite > bufferQueue)

parameter:

• bufferQueue — optional queue where filled buffers will be placed.

Persister.createPersister() constructs and returns an instance of Persister that is bound to the specified Schema. Works exactly like the Constructor.

static Persister  createPersister (SchemaManager schemaManager, RecordSchema schema, int indexMode)
static Persister  createPersister (SchemaManager schemaManager, RecordSchema schema, int indexMode, int bufferSize)

parameter:

• schemaManager — a local instance of SchemaManager connected to the Schema Registry on the server.

• schema — a schema (either a JSON string or a RecordSchema) describing the target extent on the server.

• indexMode — valid values are attributes INDEX_MODE_DEFAULT (= -1), INDEX_MODE_DEFERRED (= 0), or INDEX_MODE_IMMEDIATE (= 2).

• bufferSize — optional buffer size. Defaults to attribute DEFAULT_BUFFER_SIZE (= 32_000)

Persister.delete() deletes a single object from the extent of the server class bound to this persister.

void  delete (Long id)
void  delete (String id)

parameter:

• id — id of the object to delete. In the case where the IDKEY is a composite key, the id is a delimited string serialization of the IDKEY key properties using || as a delimiter.

Persister.deleteExtent() deletes all of the data from the extent of the server class that is bound to this persister.

void  deleteExtent ()

Persister.flush() flushes a buffer to the server or bufferQueue (see createLocalBuffer()) if there are objects in the buffer. localBuffer optionally specifies a local buffer to be flushed. This method can be used to finish a sequence of calls to add().

synchronized void  flush ()
void  flush (PersisterBuffer localBuffer)

parameter:

• localBuffer — local PersisterBuffer to be flushed

Persister.getStatistics() returns a PersisterStatistics object containing the current statistics from the buffer or a specified localBuffer (see Persister Buffer Statistics for details).

PersisterStatistics  getStatistics ()
PersisterStatistics  getStatistics (PersisterBuffer localBuffer)

parameter:

• localBuffer — local buffer where statistics are recorded.

Persister.insert() immediately writes records into the extent of the class that implements this persister's schema (unlike add(), which writes to a buffer that may not be flushed immediately).

insert( object )

inserts one or more objects into the extent of the class that implements this persister's schema. Each object contains an array of schema field values (where element 0 of the array is the first field in the schema). If localBuffer is specified, the data array is written to the local buffer, which is then immediately flushed to the server.

synchronized void  insert (Object[] object)
synchronized void  insert (Object[][] data)
void  insert (Object[][] data, PersisterBuffer localBuffer)

parameter:

• object — an array of field values.

• data — an array of field value arrays.

• localBuffer — optional local buffer

insert( record )

inserts one or more new Record objects into the extent of the class that implements this persister's schema.

synchronized void  insert (Record record)
synchronized void  insert (Record[] data)

parameter:

• record — an object implementing the Record interface.

• data — an array of Record objects.

insert( map )

inserts one or more new Map objects into the extent of the class that implements this persister's schema. Each object contains a map of schema field values (for example JsonRecord or MapRecord values).

synchronized void  insert (Map< String, Object > map)
synchronized void  insert (Map< String, Object >[] data)

parameter:

• map — Map where key is the field name and value is the field value.

• data — an array of field value maps.

insert( stream )

inserts all data in a stream into the extent of the class that implements this persister's schema. The factory function maps the data from the stream to a Record. The buffer is automatically flushed either when it becomes full or when the stream is completely consumed.

synchronized< R extends Record, T extends Object > void  insert (BiFunction< T, RecordSchema, R > factory, Stream< T > data)

parameter:

• factory — the Record factory function used to instantiate the records to which data is mapped.

  • <R> — optional Record implementation class. This can often be inferred from the factory function.

  • <T> — optional data type. This can often be inferred from the Stream.

• data — the data Stream.

Persister.reportStatistics() writes report to the console. Reports the server write statistics for activity since this persister was constructed. If localBuffer is specified, reports server write statistics for the local buffer (see Persister Buffer Statistics for more information).

void  reportStatistics ()
void  reportStatistics (PersisterBuffer localBuffer)

parameter:

• localBuffer — local buffer containing statistics to be reported

Persister.resetStatistics() resets buffer startTime and refreshs baseStatistics. This will cause a future call to reportStatistics() to report on the activity starting from the time when this method is called. If localBuffer is specified, resets statistics for the local buffer.

synchronized void  resetStatistics ()
void  resetStatistics (PersisterBuffer localBuffer)

parameter:

• localBuffer — local buffer containing statistics to be reset.

Persister.serialize() serializes an Object[], Map, or Record and returns the serialization.

ListWriter  serialize (Object[] value)
ListWriter  serialize (Map< String, Object > value)
ListWriter  serialize ( Record  value )

parameter:

• value — value to be serialized.

Persister.waitForIndexing() builds deferred indexes for the specified class on the server and waits for completion. Returns true if indexing has completed, false if timed out before index build is completed.

final boolean  waitForIndexing ()

Persister.SchemaManager() accepts an IRISConnection object and returns a SchemaManager.

SchemaManager (IRISConnection connection) throws SQLException

parameter:

• connection — a connected IRISConnection object (standard InterSystems JDBC connection object).

SchemaManager.deleteIrisExtent() deletes the persistent extent in the current namespace for the server’s local ObjectScript implementation class. Throws an exception if the schema does not exist or if there is an error encountered during delete. Also see Persister.delete(), which can delete a single object from the extent.

void  deleteIrisExtent (String schema_name)

parameter:

• schema_name — string specifying a schema name.

SchemaManager.deleteIrisSchema() deletes the schema definition from the server. If the associated ObjectsScript implementation class exists, it will also be deleted, along with any data in its extent. Throws an exception if any errors are encountered.

void  deleteIrisSchema (String schemaName)

parameter:

• schemaName — string specifying a schema name.

SchemaManager.getIrisTableClass() gets the name of the class that projects the tableName table.

String  getIrisTableClass (String tableName)

parameter:

• tableName — string specifying a table name.

SchemaManager.getSchema() gets a schema from the local Schema Registry. If it is a NamedSchema then get it from the local cache or from the server if not present in the cache. Returns an instance of a class that implements Schema.

Schema  getSchema (String name) throws JsonProcessingException

parameter:

• name — string specifying the schema name.

SchemaManager.getSchemaForClass() retrieves the schema from the connected server whose local ObjectScript implementation class is class_name If the schema for the class already exists and is up to date then that schema is retrieved. Otherwise, a new schema is generated from the class and returned.

RecordSchema  getSchemaForClass (String className) throws JsonProcessingException

parameter:

• className — name of the ObjectScript class that implements the current schema.

SchemaManager.isIrisClassDefined() return true if the ObjectScript class is defined on the server.

boolean  isIrisClassDefined (String name)

parameter:

• name — name of the ObjectScript class.

SchemaManager.isIrisSchemaDefined() return true if the schema is defined in the Schema Registry

boolean  isIrisSchemaDefined (String name)

parameter:

• name — string specifying the schema name.

SchemaManager.isSchemaUpToDate() returns true if the schema matches ObjectScript implementation class class_name on the server.

boolean  isSchemaUpToDate (String class_name)

parameter:

• class_name — name of the ObjectScript class.

SchemaManager.parseSchema() parses the schema source, returning an instance of a class that implements Schema.

Schema  parseSchema (String source) throws JsonProcessingException
Schema  parseSchema (JsonNode source) throws JsonProcessingException

parameter:

• source — source of the schema; either a String or a JsonNode (an instance of com.fasterxml.jackson.databind.JsonNode)

SchemaManager.synchronizeSchema() synchronizes a schema (either a JSON string or a RecordSchema) with the connected Schema Registry and returns the synchronized schema as a RecordSchema. If the schema is already defined in the Schema Registry then it is returned. If an ObjectScript class whose name matches the name defined by schemaSource exists then a schema is generated from that ObjectScript class and returned. Otherwise, schemaSource is added to the Schema Registry and an ObjectScript implementation class is generated. The resulting schema from the server is then returned.

When there is a matching schema already defined in the Schema Registry, it is compared with the schemaSource. If there is a difference then those differences are resolved, possibly generating a new version of the local implementation class. Existing data is kept compatible with the new class.

RecordSchema  synchronizeSchema (String schemaSource) throws PersisterException, JsonProcessingException
RecordSchema  synchronizeSchema (RecordSchema schema) throws PersisterException
RecordSchema  synchronizeSchema (String schemaSource, String annotations)
RecordSchema  synchronizeSchema (RecordSchema schema, String annotations) throws PersisterException

parameter:

• schemaSource — JSON formatted schema definition

• schema — a RecordSchema formatted schema definition

• annotations — JSON formatted object with indices field (see SchemaBuilder.index() and indexes()).

Throws PersisterException if the server reports a problem. JsonProcessingException is thrown by the Jackson JSON parser.

SchemaManager.synchronizeSchemaWithIris() allows the manager to establish a new connection and synchronize using that connection. Once connected, it synchronizes a schema definition with the connected server and returns the corresponding RecordSchema retrieved from the Schema Registry at that location. If annotations is specified, the index definitions contained in the annotation are also applied. If the named schema already exists on the server then it is simply returned. If it does not exist but a class of the same name does exist then a schema is generated on the server and returned. Otherwise, the schema is saved to the server, compiled, and the resulting schema is then returned. The new connection is closed when this method returns.

static RecordSchema  synchronizeSchemaWithIris (RecordSchema schema, IRISConnection connection) throws SQLException
static RecordSchema  synchronizeSchemaWithIris (RecordSchema schema, IRISConnection connection, String annotations) throws SQLException

parameter:

• schema — RecordSchema sent to the server

• connection — IRISConnection object connected to the server

• annotations — JSON formatted object containing index definitions

Throws SQLException if there is an issue obtaining a connection to the server.

SchemaBuilder.array() builds an array schema and returns a JSON string containing the schema.

static String  array (String itemsType)
static String  array (Schema itemsType)

parameter:

• itemsType — Schema object or JSON schema string defining the type of the array items

SchemaBuilder.date() returns a LogicalSchema of type date as a JSON formatted string (see LogicalSchema Types).

static String  date ()

SchemaBuilder.decimal() returns a LogicalSchema of type Decimal as a JSON formatted string (see LogicalSchema Types).

static String  decimal (int precision, int scale)

parameter:

• precision — integer specifying the maximum number of significant digits to be stored.

• scale — (optional) integer specifying the number of digits to the right of the decimal point. Defaults to 0.

SchemaBuilder.embedded() accepts an embedded schema description (in either JSON or RecordSchema format) and returns a string containing a JSON formatted embeddedSchema.

Note: Embedded types are currently not fully supported by the builder.

static String  embedded (RecordSchema embeddedSchema)
static String  embedded (String embeddedSchema)

parameter:

• embeddedSchema — (RecordSchema or String) schema describing the embedded record.

SchemaBuilder.index() returns an SchemaBuilder.IndexBuilder that can be used to build an index definition.

static IndexBuilder  index (String indexName)

parameter:

• indexName — name of the index to build.

SchemaBuilder.IndexBuilder

The IndexBuilder class has the following methods, all of which can be chained. The final call in the chain must be the complete() method, which returns the finished index definition as a JSON string.

              IndexBuilder ()
IndexBuilder  isExtent ()
IndexBuilder  isIdkey ()
IndexBuilder  isPrimaryKey ()
IndexBuilder  isUnique ()
IndexBuilder  on (String field)
IndexBuilder  withName (String name)
IndexBuilder  withType (String type)
IndexBuilder  withType (IndexType type)
      String  complete ()

SchemaBuilder.indexes() returns a SchemaBuilder.AnnotationsBuilder object implementing addIndex() methods used to create a schemas.LogicalSchema annotations object, typically containing one or more index definitions.

Indexes are not part of a schema but can be defined and passed to an IRIS server when synchronizing a schema. Indexes are processed by the server when generating the ObjectScript class.

static AnnotationsBuilder  indexes ()

SchemaBuilder.AnnotationsBuilder

AnnotationsBuilder has the following methods, all of which can be chained. The final call in the chain must be the complete() method, which returns the finished annotations object as a JSON string.

AnnotationsBuilder  addExtent (String name, IndexType type)
AnnotationsBuilder  addId (String name, String field)
AnnotationsBuilder  addIndex (IndexBuilder index)
AnnotationsBuilder  addIndex (String index)
AnnotationsBuilder  addIndex (String name, String field)
AnnotationsBuilder  addIndex (String name, String field, IndexType type)
            String  complete () 

SchemaBuilder.infer() creates a schema by inference from a data value, a class instance, a class type, or a Record.

infer( value )

Infers a schema from a value and returns a string containing a JSON formatted schema describing the value.

static String  infer (Object value)

parameter:

• value — a data value, can be a simple or complex value.

infer( type )

Infers a schema from a Java Type or Java Class object, and returns a string containing a JSON formatted schema describing the type.

static String  infer (Class type)
static String  infer (Type type)

parameter:

• type — a Java Type or Java Class object.

infer( record )

Infers a schema from the types of each element in the specified Object[] and returns a string containing a JSON formatted schema. If fieldName is specified, each value in the generated schema is assigned a name from the fieldName array.

static String  infer (Object[] record)
static String  infer (Object[] record, String schemaName)
static String  infer (Object[] record, String schemaName, String[] fieldName)

parameter:

• record — Object[] containing representative field values

• schemaName — optional name of the schema to generate.

• fieldName — optional String array of field names to assign to Record fields.

SchemaBuilder.logical() returns an instance of SchemaBuilder.LogicalSchemaBuilder, which can be used to create a schemas.LogicalSchema object.

static LogicalSchemaBuilder  logical ()

SchemaBuilder.LogicalSchemaBuilder

LogicalSchemaBuilder has the following methods, all of which can be chained. The final call in the chain must be the complete() method, which returns the finished logical schema definition as a JSON string.

LogicalSchemaBuilder  withLogicalType (String logicalType)
LogicalSchemaBuilder  withProp (String propName, String value)
LogicalSchemaBuilder  withType (Schema type)
LogicalSchemaBuilder  withType (String type)
              String  complete ()

SchemaBuilder.map() builds a map schema and returns a string containing a JSON array formatted schema.

static String  map (Schema keysSchema, Schema valuesSchema)
static String  map (String keysType, String valuesType)

parameter:

• keysSchema — Schema instance that is type of the map keys

• valuesSchema — Schema instance that is type of the map values

• keysType — JSON formatted Schema that is type of the map keys

• valuesType — JSON formatted Schema that is type of the map values

SchemaBuilder.normalizeAsJson() calls String.trim() on any value starting with {, [, or " and returns the trimmed string. If it begins with any other character, value is returned in double quotes.

static String  normalizeAsJson (String value)

parameter:

• value — String value to be normalized.

SchemaBuilder.primitive() builds a primitive schema and returns string containing a JSON formatted schema.

static String  primitive (String type)

parameter:

• type — String specifying primitive schema type. Valid values are string, bytes, short, int, long, float, double, boolean, or null.

SchemaBuilder.record() returns an instance of subclass RecordSchemaBuilder, which can be used to create a JSON schema string.

static RecordSchemaBuilder  record ()

SchemaBuilder.RecordSchemaBuilder

RecordSchemaBuilder has the following methods, all of which can be chained. The final call in the chain must be the complete() method, which returns the finished record schema definition as a JSON string:

RecordSchemaBuilder  addField (String name)
RecordSchemaBuilder  addField (String name, String type)
RecordSchemaBuilder  addField (String name, Schema type)
RecordSchemaBuilder  addField (String name, Class type)
RecordSchemaBuilder  addField (String name, Type type)
RecordSchemaBuilder  addField (RecordField field)
RecordSchemaBuilder  asEmbedded ()
RecordSchemaBuilder  asFinal ()
RecordSchemaBuilder  category (String category)
             String  complete ()
RecordSchemaBuilder  extendsClasses (String superClasses)
RecordSchemaBuilder  extendsSchema (RecordSchema superSchema)
RecordSchemaBuilder  withFinal (boolean isFinal)
RecordSchemaBuilder  withName (String name)
RecordSchemaBuilder  withName (SchemaName name)

SchemaBuilder.reference() returns a LogicalSchema of type intersystems-reference as a JSON formatted string (see LogicalSchema Types).

static String  reference (String referencedSchema)

parameter:

• referencedSchema — the schema that is referenced

SchemaBuilder.timeMicros() returns a LogicalSchema of type time-micros as a JSON formatted string (see LogicalSchema Types).

static String  timeMicros ()

SchemaBuilder.timeMillis() returns a LogicalSchema of type time-millis as a JSON formatted string (see LogicalSchema Types).

static String  timeMillis ()

SchemaBuilder.timestampIrisPosix() returns a LogicalSchema of type IRIS POSIX timestamp as a JSON formatted string (see LogicalSchema Types).

static String  timestampIrisPosix ()

SchemaBuilder.timeStampMicros() returns a LogicalSchema of type timestamp-micros as a JSON formatted string (see LogicalSchema Types).

static String  timeStampMicros ()

SchemaBuilder.timeStampMillis() returns a LogicalSchema of type timestamp-millis as a JSON formatted string (see LogicalSchema Types).

static String  timeStampMillis ()

SchemaBuilder.uuid() returns a LogicalSchema of type UUID as a JSON formatted string (see LogicalSchema Types).

static String  uuid ()