Implementing Schemas with SchemaManager
In order to persist date, the Persister requires a schema structure that is understood by both the Persister application and the server. The application must have a way to retrieve valid schemas from the server’s persistent Schema Registry, and to update existing schemas or add new ones. On the server side, the Schema Registry synchronization process must ensure that each schema has a corresponding ObjectScript class extent, creating a new extent if one does not already exist.
SchemaManager is the primary interface between a Persister application and the server. The SchemaManager provides each Persister instance with a validated schema and a connection to the server. The SchemaManager also communicates with the Schema Registry process, ensuring that application and server schema definitions are synchronized. To accomplish this, the SchemaManager provides the following services to the Persister application:
-
Synchronizes schema definitions with the Schema Registry, making a local cache of validated schemas available to the application.
-
Provides the IRISConnection object that connects the Persister to the server.
-
Adds new schema definitions to the Schema Registry (see Designing Schemas with SchemaBuilder)
-
Retrieves existing schemas by name, and creates new ones from existing ObjectScript classes (see Acquiring Schemas from the Server)
-
Includes schema and extent utilities that provide current information and allow schemas or extents to be deleted.
The following sections provide detailed information on synchronizing schemas, acquiring them from the server, and managing them with various utilities.
Synchronizing Schema Definitions
Each SchemaManager object maintains a local cache of schemas for the current application. In each InterSystems IRIS namespace, schema records are persisted in a Schema Registry, and are implemented in associated ObjectScript class extents. A schema is said to be synchronized between the application and the server when:
-
The named schema is present in the Schema Registry on the server.
-
The Schema Registry record is implemented by an existing ObjectScript class extent.
-
The SchemaManager object in the application has a schema in its local cache that matches the one in the Schema Registry.
A schema is implemented by calling the synchronizeSchema() method, which passes it to the Schema Registry process on the server. If the server process is able to synchronize the schema, it is returned as canonical RecordSchema object, which is also stored in the SchemaManager’s local cache.
The synchronization process on the server can act in several different ways, depending on what information is already on the server:
-
If the requested schema does not exist in the Schema Registry, the process adds a new record to the Registry and creates a corresponding ObjectScript class extent.
-
If a matching schema is already defined in the Schema Registry and is implemented by a matching ObjectScript extent, the process simply returns the currently defined RecordSchema.
If a schema of the same name is in the Registry, but does not match the parameter passed by synchronizeSchema(), the differences are resolved. The resolution may require generating a new version of the local implementation class. In this case, the new class will be kept compatible with existing data.
-
If the schema does not exist in the Registry but an ObjectScript class with the same name exists, then a schema is generated from that ObjectScript class and synchronized.
Once the schema is synchronized, a Persister can be used to store data in the extent of the implementing ObjectScript class (see Serializing Data with Persister).
Acquiring Schemas from the Server
SchemaManager has two methods to acquire schemas from existing server information:
-
getSchema() gets and synchronizes an existing schema from the Schema Registry.
-
getSchemaForClass() creates and synchronizes a schema from an existing ObjectScript class.
Given a schema name, getSchema() will first check to see if the requested schema is already in the local cache. If not, it checks the Schema Registry on the server. If the schema is present there then it is retrieved, placed in the local cache and returned to the caller.
Schema demoSchema = mgr.getSchema("Demo.Hello");
System.out.println(demoSchema.toJson());
The resulting schema may contain some metadata added by the Schema Registry.
{"name":"Hello","namespace":"Demo","final":false,"importFlags":0, "category":"persistent",
"type": "record", "fields": [{"name":"greeting", "type":"string"}]}
getSchemaForClass() — A schema can also be generated from an existing ObjectScript class. If the schema for that class already exists and is up to date then the previously defined schema is retrieved. Otherwise, a new schema is generated from the class and returned to the caller.
RecordSchema someSchema = schemaManager.getSchemaForClass("Demo.someClass");
Schema and Extent Utilities
The following examples assume that there is a schema with namespace Test.Demo and name Hello. By default the corresponding ObjectScript class will have a package name and short name identical to the schema namespace and name. The corresponding SQL table name would be Test_Demo.Hello (see Designing Schemas with SchemaBuilder for more information on schema names).
All of these SchemaManager methods act only on schemas stored in the Schema Registry on the server. They do not affect or require a schema with the same name on the application side.
-
deleteIrisSchema() — deletes the schema definition from the Schema Registry on the server. Also deletes the corresponding ObjectScript class (if it exists), and all data in the class extent.
manager.deleteIrisSchema("Test.Demo.Hello"); -
isIrisSchemaDefined() — returns true if a schema with the specified name is defined in the Schema Registry.
boolean isDefined = manager.isIrisSchemaDefined("Test.Demo.Hello"); -
isSchemaUpToDate() — returns true if the structure of the specified ObjectScript class matches the corresponding schema in the Schema Registry.
boolean isCurrent = manager.isSchemaUpToDate("Test.Demo.Hello");
-
deleteIrisExtent() — given a schema name, deletes the extent of the associated ObjectScript class.
manager.deleteIrisExtent("Test.Demo.Hello"); -
isIrisClassDefined() — returns true if the ObjectScript class is defined on the server. The class does not have to match an entry in the Schema Registry.
boolean isDefined = manager.isIrisClassDefined("Test.Demo.Hello"); -
getIrisTableClass() — gets the name of the ObjectScript class that projects the specified SQL table.
String tableClass = manager.getIrisTableClass("Test_Demo.Hello");In this example, a query on table name Test_Demo.Hello would return class name Test.Demo.Hello, where Test.Demo is the class package name and Hello is the unqualified class name.
