API

The CRISTAL API

This documentation should be the most up-to-date available. Be sure to check the source:changelog to be sure.

Maven sites: Initial Release: 3.0 (javadoc)

CRISTAL is a system that managed description-driven objects, known as [Item]s within the system. These are objects that gain all of their application-specific behaviour through configuration, rather than compiled code. This configuration data, known as 'Descriptions' comprises of DAG-oriented workflow definitions, XML Schemas and script fragments, which interact to provide the full lifecycle of the Item they are describing. In CRISTAL, the description data is also stored in other Items, which are also described using the same mechanism. This means that CRISTAL can store previous versions of descriptions, so that previous states of the system are preserved, and full provenance of both the application and its data are completely preserved.

CRISTAL allows for three types of process:

• Server - a server process is where Items are managed. They are instantiated, their workflows are orchestrated, and outcomes and other data are written to them. They do not function as CRISTAL Agent implementations. and so they do not perform any of the work that generates those outcomes: the only user-generated code that is executed in a server is to decide which branch of a workflow to follow in the event of a fork (OR, XOR, LOOP splits). Item and Agent IORs point to a server's CORBA endpoint. Servers are authenticated against LDAP servers as root rather than as a specific CRISTAL Agent.
• Client - these processes authenticate against a CRISTAL Agent, perform work as that Agent's implementation, and recording that work and any data generated by submitting completed Jobs to the Item that required the work. They interact with servers by locating Items and Agents, retrieving data from them, querying Jobs from Items and executing those Jobs by filling in the Outcome and requesting the transition. During the execution process, the Agent will execute any Scripts associated with the selected Activity, which may modify the outcome or otherwise change the Item's stateby interacting with Predefined Steps in the its workflow.
• Shared clients - these processes function as clients, but for many agents instead of just one. They forward the functionality of item browsing and job execution to some external Agent implementation. An example would be a web server process, which can accept connections from many users via web browsers at the same time.

When we refer to the 'CRISTAL API' this refers to the client functionality, as the server code should not be modified by end users or developers. As an expansion of the above, client functionality breaks down into five areas:

1. Authentication
2. ResolvingEntities
3. QueryingEntityData
4. JobExecution
5. InteractingWithPredefinedSteps

CRISTAL Process Structure

This section details the objects that are created during CRISTAL process creation, and how to interact with them.

Gateway

Singletons that CRISTAL processes use to find and communicate with Items

1. Gateway - The class that CRISTAL processes initialize, which contains CRISTAL's API singletons.
2. CRISTAL_Properties - Cristal process properties. Origin, usage and standard sets.
3. Lookup - Item and Agent Directory. Paths and resolution.
4. TransactionManager - Persistency of Cristal local objects.
5. EntityProxyManager - Client proxies to cristal items and agents.
6. CastorXMLUtility - Mapping between Cristal local objects and Schema described XML fragments using the kernel mapfiles.

Modules

Bundles of Items that add functionality to a kernel instance

1. ModuleXML - structure and syntax of the module xml specification.
2. Info - Module metadata
3. Config - Module-supplied configuration properties
4. Scripts - Scripts that should run during the module's lifecycle.
5. Imports - Resources and entities that the module supplies.
6. ModuleItem - representation of a module as a Cristal Item.

Scripting

Interacting with Items in activity and routing scripts

1. PredefinedSteps - special activities that execute code on the server to modify aspects of the Item