|
7.0 Action Request System Java API | |||||||||
| PREV NEXT | FRAMES NO FRAMES | |||||||||
See:
Description
| Packages | |
| com.remedy.arsys.api | |
AR System Java API
|
|
The Action Request System 7.0 Java API is an application programming interface to integrate with the AR System. The AR System Java API is a collection of classes, interfaces, and relationships that abstract the AR System C API and hide some of its details, such as the memory management for data structures, managing connections, and so on. Using the Java development environment, you can use the AR System Java API to communicate with the AR System server without programming in C.
In addition, many of the Java API objects are classes modeled after the Enterprise Java Beans (EJB) requirements for objects. Most of the methods required for an object to be classified as EJB (for example, load or store) are implemented in the AR System Java API.
If you have comments or suggestions about this documentation, contact Remedy Information Development by email at .
The main change in 7.0 is a new arapi70.jar file. As a result, if you link to the new arapi70.jar file, you must make changes to your programs, including the following:
In addition, the following new Java classes were added in the 7.0 release:
Otherwise, the main program structure of your AR System Java API programs need not change.
As a Java "wrapper," the Java calls are mapped to the C API through the Java Native Interface (JNI) layer. The AR System Java API is not "pure" Java. Accordingly, you can only use the AR System Java API on supported AR System platforms, and not simply any platform that is running a Java Virtual Machine. Specific platforms supported by the AR System here include:
The intended audience of the AR System Java API is programmers who are writing the following:
The AR System Java API with its classes and methods is designed to both adhere to object-oriented methodology and to be functionally equivalent to the AR System C API with its functions and data structures. In this implementation, the AR System server objects are treated as "objects" in the AR System Java API. All functionality of the AR System C API is represented as discrete objects used to create, retrieve, and manipulate AR System server objects and entries submitted by end users (or other client programs) in the database. You should note, however, that there is not a 1:1 correspondence in the mapping between the Java API and the C API.
You can also use the AR System Java API to manipulate data in the database. "Objects" you can manipulate with the AR System API include not only schemas, workflow, menus, and so on, but you can also use the Entry classes to manipulate entries in a form in different ways. For example, you can use the Java API to get a list of entries.
Note In the implementation of the AR System Java API, there are certain naming conventions, design patterns, and abstractions that you need to be familiar with in order to use it. If you are experienced with the AR System API, you shouldn't find it difficult to make sense of the Java API wrapper. However, you will want to be aware of how AR System C structures and functions correspond to the Java objects before you begin using the AR System Java API.
A) Factory Design Pattern [Return to TOC]
In the Java API, server objects are exposed as Java objects. As a programming convenience, the AR System Java API uses factory design patterns to create, destroy, and retrieve server objects.
The IARObjectFactory class is the superclass of the various object factory classes, for example, ActiveLinkFactory, SchemaFactory, and so on. Each server object contains the newInstance( ) method for creating instances of objects. You also must use the releaseInstance(Object obj) method to release the instance of the object. You can see a more detailed example in sample code.
Each server object has a corresponding special factory class (<Object>Factory, for example, SchemaFactory) that imposes a structure on each object. Each factory class then has methods for manipulating instances of that server object. For example, to create a schema, you would use SchemaFactory to instantiate a schema object.
Each <Object>Factory contains three different find methods (find, findByKey, findObjects) to query for server object instances that contain data retrieved from the AR System. In this way, you use the factory class methods of a server object to create new objects, or you use the find methods of the factory classes to search for existing objects on the AR System server. You use the get/set functions to allow you either to retrieve (getSchemaType) or to set (setSchemaType) data in that object. Then you would use the following methods to perform various operations on the AR System server:
You can see a more detailed example in sample code. This sample code uses the SchemaFactory to create a schema.
B)
Proxy Design Pattern [Return
to TOC]
The Proxy design pattern is used for handling the structural aspects of server objects, such as memory management and access to the AR System server. The Proxy class that performs this work is not visible to users of the AR System Java API and is designed for internal use only. The Proxy class contains all the native methods required for interaction with the AR System. Each of these native methods perform data conversion from C to Java (or Java to C) and "wrap" the AR System C API calls.
C) Criteria Objects [Return to TOC]
Criteria objects are used to evaluate and screen the results coming back to your Java program from the AR System. Criteria objects lets you define what attributes you want to retrieve. The following criteria objects are available in the Java API:
All server objects (workflow objects like active links, filters, and escalations; entry objects, support file, menu, field, form, and view objects) have criteria objects that allow you to specify which attributes to retrieve. For example, using the ActiveLinkCriteria object, you can specify name, the execution order, timestamp information, object properties, etc. Criteria objects follow this naming convention: <Object>Criteria (for example, ContainerCriteria, FilterCriteria, EntryCriteria, and so on.).
You can see a more detailed example in sample code that uses the findByKey method to retrieve a particular schema specified by the SchemaCriteria class.
D) Criteria List Objects [Return to TOC]
All server object lists that can be retrieved in the AR System C API have a corresponding criteria object as well. The list criteria object abstracts query information applicable to a collection of objects. The following criteria objects are available in the Java API:
Criteria objects for retrieving lists follow
this naming convention:
<Object>ListCriteria
(for example, ContainerListCriteria,
EntryListCriteria,
and so on.). The exception to this naming convention is with workflow (active
link, filter, and escalation) objects, which use a common list criteria class
called WorkFlowObjectListCriteria.
You can see a more detailed example in sample code that uses the find method to retrieve a list of schema names specified by the SchemaListCriteria class. There is also sample code that uses the find method to retrieve a list of active link names specified by the WorkFlowObjectListCriteria class.
E) Cloning Objects [Return to TOC]
Warning: Cloning was made available for all objects in the AR System Java API. However, in the 5.x and 6.x releases of the AR System Java API, the clone() method may not copy the underlying objects as expected. It is unstable and may crash any programs that use this method.
F) Exception Handling (Errors) [Return to TOC]
Errors are modeled through the ARException class. All error messages that are returned by the server are thrown as an ARException in theJava API.
To implement your programs, you will want to use the following idioms in your Java program. All AR System Java API programs follow the same basic outline:
Note This step illustrates another difference between the C API and the Java API. In the C API, the control argument in each call to the server provides access information (user and server information and initialization information) on per call basis. In the Java API, you provide the user and server information separate from the calls you will make for that operation.
Because Java handles the deallocation of memory automatically (using garbage collection), another key difference between the C API and the AR System Java API is that when references to an object no longer exist, that object is assumed to no longer be needed, and then the memory occupied by that object is reclaimed. So, freeing allocated memory and shutdown/cleanup of the general structure of a C API program do not have a counterpart in an AR System Java API program. However, in an AR System Java API program, you must use the clear method to release context (user and server) information as well as other methods of the classes you use, and to use the releaseInstance method of the factory object to reclaim memory that has been allocated to a factory object. The underlying resources are not touched by garbage collection. They must be released.
The steps for the AR System Java API Program Structure are summarized in the following diagram.
Diagram of AR System Java API Program Structure
A) Naming Conventions: How C Structures and Functions Correspond to Java API Objects [Return to TOC]
Without too much difficulty, developers who are familiar with the AR System C API can find their way in the Java API. There are common terms in C that have their parallel in Java. The naming conventions of the Java API objects follows the basic pattern listed in the table below:
|
Differences in Naming Conventions |
||
|
C API |
Java API |
Differences |
| AR<object>Struct (see exceptions below) | <object>Info |
|
| AR<object>List | <object>Info (an array) | Because lists are handled as arrays, the -List suffix becomes the -Info suffix. For example, ARPermissionList from the C API corresponds to the PermissionInfo class in the AR System Java API. The exceptions to these naming conventions pertain to the classes used for retrieving lists of entries and lists of fields. For example, in the C API, use AREntryListList to return a list of entries as concatenated strings. In the Java API, you would use the find and findObjects factory methods to retrieve a list of entries as concatenated strings. See Program Structure for more information. |
| NameType | NameID | The C API suffix -Type becomes -ID in the Java API, so that a variable NameType becomes NameID. |
| Get | load, findByKey | |
| Set | store | |
| Create | create | |
| Delete | remove | |
| GetList | find, findObjects | |
B)
Exceptions to Naming Conventions [Return
to TOC]
The ARControlStruct is an exception to the naming conventions described here, because user information required to perform AR System operations is handled slightly differently in the Java API. The ARServerUser class is used to handle user login information for object operations. You specify user information via the ARServerUser class when you perform a setContext operation for a specific class of server object.
To use the AR System Java API, you must have the AR System C API library and *.dlls installed on the same machine where you run the AR System Java API. Please see the C API Reference Guide for more information.
A) Contents of the AR System Java Installation [Return to TOC]
B) Windows Environment Setup [Return to TOC]
The following information applies to Windows environments.
| Compiler | Requires J2SE Software Development Kit (SDK) 1.4.2 (or higher). To install the JDK, use the instructions provided by Sun Microsystems. |
| JAR Files and CLASSPATH |
|
| DLLs and System Path |
The Java API requires the AR System API *.dlls.
|
C) UNIX Environment Setup [Return to TOC]
Implementations of the JDK on some operating system environments may vary, but for convenience you may want to make sure of the following:
| Compiler | Requires J2SE Software Development Kit (SDK) 1.4.2 (or higher). To install the JDK, use the instructions provided by Sun Microsystems. |
| JAR Files and CLASSPATH |
|
| PATH | Update your PATH environment variable to include the bin directory for the JDK per the installation instructions from Sun. |
| Library Path |
Set the library path environment variable to where the libarjni.<operating_system> file is installed for your particular UNIX OS:
|
The final step in the deployment process occurs when the software is installed on individual user system. This step includes installing and configuring the Java Runtime Environment on the individual user system.
Tips
java -D java.library.path = <directory>; -classpath .;arapi70.jar JavaDriver
The following are helpful terms and definitions when using the AR System Java API. Some terms are strictly Java terms that are defined here in terms of their use in the documentation for the AR System Java API.
|
Term |
Definition |
| ARException | The class that is used for handling errors from the AR System server. Use the ARException methods to obtain status information (using the StatusInfo class) and to describe errors. |
| ARServerUser | The ARServerUser class represents user information that contains login information for accessing the AR System. You use a ARServerUser object to initialize calls to a particular AR System server. |
| clear | A method that clears all of the references to member objects. Use the clear function in your programs after you have used an object and want to clear references to the object and prepare it for garbage collection. Use the clear method for objects that explicitly interact with the server. |
| clone | A method that is part of the AR System Java API objects for generating a deep copy of the object on which it is called. When a clone is made, the constructor for the object being cloned is not called, because the clone is an exact copy of the original. |
| Context | The user session information that pertains to the current operation within an object. When you set the context using setContext for an operation, you supply the user information (user name, password, etc.) contained in the ARServerUser object for an operation performed in the specified session. |
| create | A
server object member method that creates an object on the server
specified in ARServerUser. |
| Factory | A programming design pattern used to create and manipulate server objects, such as forms, entries, and workflow objects in the AR System Java API. Each server object has a factory class (for example, ActiveLinkFactory). |
| find |
Server object factory member method that returns the following:
|
| findByKey | Server object factory member method that returns information about the server object (or entry) specified by the <Object>Key (for example, ActiveLinkKey) and <Object>Criteria (for example, ActiveLinkKey). This information is returned from the AR System server specified in the ARServerUser object. |
| findObjects | Server object factory member method that returns a list of server objects (or entries) specified by the object's <Object>ListCriteria and <Object>Criteria objects. This information is returned from the AR System server specified in the ARServerUser object. |
| Info | The
suffix for any class that represents an AR System C API data structure.
For example: DisplayInstanceInfo
in the Java API maps to ARDisplayInstaceStruct
in the C API. For more information, see Naming Conventions. |
| Interface |
The interface functions as the protocol followed by classes that extend it. In the AR System Java API, there are five interfaces that specify what a class must do, but not how it does it. The interfaces are:
Constants is also defined as an interface. It contains all the constant values used in the AR System Java API. |
| JNI | The Java Native Interface. This is a C++ layer that takes calls from Java and makes corresponding calls to the C API. This happens transparently. |
| load | Server object member method that populates an object with information from the AR System server. |
| <Object>ListCriteria | The special class for a server object (for example, EntryListCriteria, ContainerListCriteria) used to specify the query information, or the format and scope of the list of query results returned from the AR System server. |
| <Object>Key | The special class for a server object (for example, ActiveLinkKey, FilterKey, etc.) used for cloning an object or retrieving a specific instance of an object. An object's object key uniquely identifies that object. |
| <Object>Criteria | The
special class for a server object (for example, SchemaCriteria,
EntryCriteria)
used to specify the criteria by which an object is to be retrieved from
the server specified in the ARServerUser
object. The object criteria retrieves information for each object
selected by the criteria list object. The <Object>Criteria class has methods to specify the list of object
information or attributes to be retrieved. For example, you can retrieve
certain field values for an entry using the EntryCriteria
object, or you can retrieve owner information for a schema using the SchemaCriteria
object. By default, none of the object attributes are retrieved unless
otherwise specified. See also <Object>ListCriteria. |
| Package | The
package is a name space in Java for all objects and classes pertaining
to the AR System Java API. In the case of the AR System, the package
name represents the directory structure of the classes: com.remedy.arsys.api |
| Proxy | The Proxy class contains all the methods for loading the ARServerUser information with the session ID and specific information that pertains to the AR System API call that gets made with the AR System Java API. The proxy is transparent and not directly accessible through the AR System Java API. |
| remove | Server object member method that deletes an object with the indicated ID from the specified server. |
| store | Server object member method that updates an object on the database. |
|
7.0 Action Request System Java API | |||||||||
| PREV NEXT | FRAMES NO FRAMES | |||||||||