API

The CRISTAL-ISE Client API

CRISTAL-ISE is a system that manages description-driven objects, known as Items. 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-ISE 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 state by 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-ISE 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. Item directory browsing and resolution
3. Item data access
4. Obtaining and Executing Jobs to submit new Outcomes
5. Changing the state of an Item during execution

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. Properties - Cristal process configuration properties. Origin, usage and standard sets.
2. Lookup - Item and Agent Directory. Paths and resolution.
3. TransactionManager - Persistency of Cristal local objects.
4. ProxyManager - Client proxies to cristal Items and Agents.
5. ModuleManager - Loads, imports and initializes CRISTAL modules, which supply additional functionality through bundled Items.
6. ResourceLoader - loads Java resources from the kernel or Module jars.
7. CastorXMLUtility - Mapping between Cristal local objects and Schema described XML fragments using the kernel mapfiles.

Server only singletons

1. LookupManager - writes to the Item and Agent directory.
2. ProxyServer - manages client Item subscriptions, and informs them of changes to Items.
3. CorbaServer - creates and manages Item objects as they are invoked over CORBA.

Modules

Bundles of Items that add functionality to a kernel instance

1. ModuleStructure - the file format and structure of a module.
2. ModuleXML - structure and syntax of the module xml specification.
3. ModuleItem - representation of a module as a Cristal Item.

Bootstrap

Read the Items of the modules and instantiate or update them to initialize the application

1. Boot-Sequence-of-Server - sequence of events involved in starting a CRISTAL server process

CRISTAL-iSE Building Blocks

Properties

The venerable key-value pair is used heavily to achieve flexibility

1. PropertyDescription - Properties that describe Item 'types'
2. Property - Properties of Item itself
3. VertexProperty - Properties used in activities and collections

LifeCycle

LifeCycle defines and execute the business logic implemented by the Item

1. PredefinedStep - built-in activities that execute code on the server to modify the fundamental aspects of the Item
2. Activity - represents a task that needs to be done by an Agent
3. State-Machine - defines the possible transition available to execute an Activity
4. Job - represents a possible transition by a particular Agent of an Activity

Collections

Collections declare relationships between Items

1. Dependency - Most basic collection type to reference Items
2. Aggregation - Composition a fixed number of Item, which are individually typed
3. CollectionDescription - Defines collection instances to be created (Dependency/Aggregation)

Scripting

Interacting with Items in activity, routing and instantiation scripts

1. Script
2. Instantiation Script

Proxies

Proxies client-side representation of Items and Agent, they are the primary tool for application developers.

1. ItemProxy - Wrapper of the communication with Item.
2. AgentProxy - Subclass of ItemProxy, has utility methods for Job Execution.
3. Caching - ItemProxy caches data loaded from the Item to reduce communication.

Graph

Library to support graph representation within the framework

1. Renderer - Renders the graph on Graphics2D canvas of AWT so it can be shown as PNG or SVG