This article is part of my New in ARS 7.1 series and my Java ARS API series.
One of the major changes for ARS 7.1 is that it has a new Java API. It looks and feels like it is a complete rewrite from the original API. From the BMC documentation:
The primary goals of this API revision are to simplify the interface and eliminate drawbacks of the 7.0 API. Changes include:
- Simplified interface.
- More Java-friendly.
- Use of Java typed-collections.
- Improved stability, performance, and ease of deployment.
- Increased developer productivity by means of better named API methods, intellisense of IDEs, and documentation.
- Drive towards a “pure” Java implementation and eventually eliminate Java Native Interface (JNI) use.
While this is all true, one of the main drawbacks is that you almost completely have to rewrite old Java applications if you want to use them with the new API.
However if you are writing new Java applications this new API is the best release ever. I only played around with it a short time but was really impressed by how it all fits together. Lots and lots of irritating String wrappers have been dropped, multiple ‘nested’ items have become uncluttered and the toString functions now returns nice Strings instead of garbled nonsense.
Sample Code
For the sample code (and all ARS Java API 7.1 code) to work you will need Java 1.5.0_12 or later. I personally use Eclipse 3.2 Europa (Eclipse IDE for Java Developers) as my development environment, however you can of course use any.
Full source code of samples with comments download (click)
Let’s take a look at creating a new Entry in a Form (yes, they are called Forms now!)
ARServerUser context = new ARServerUser("Demo", "", "", "localhost");
Entry newEntry = new Entry();
newEntry.put(7, new Value(0));
newEntry.put(2, new Value("JavaSubmitter"));
newEntry.put(8, new Value("Short Description"));
try{
System.out.println(context.createEntry("XQSR:JavaExample", newEntry));
}
catch(ARException arException){
arException.printStackTrace();
}
}
Yes, that is indeed all, no need for anything more. The Entry Class now holds a map with the Field IDs (integers) and Value objects. This is a great improvement over the EntryItem[] entryList = new EntryItem[3]; ‘fun’ that was in previous API versions.
As for retrieving an Entry, changing values and submitting it again the following example should give a quick impression:
ARServerUser context = new ARServerUser("Demo", "", "", "localhost");
int[] fieldIDsToRetrieve = new int[6];
fieldIDsToRetrieve[0] = 1;
fieldIDsToRetrieve[1] = 2;
fieldIDsToRetrieve[2] = 3;
fieldIDsToRetrieve[3] = 5;
fieldIDsToRetrieve[4] = 6;
fieldIDsToRetrieve[5] = 7;
try{
Entry retrievedEntry = context.getEntry("XQSR:JavaExample", "000000000000001", fieldIDsToRetrieve);
for(int i=0; i<fieldIDsToRetrieve.length; i++){
System.out.println(retrievedEntry.get(fieldIDsToRetrieve[i]) );
}
retrievedEntry.put(8, new Value("I am updated"));
context.setEntry("XQSR:JavaExample", "000000000000001", retrievedEntry,new Timestamp(0), 0);
}
catch(ARException arException){
arException.printStackTrace();
}
We fill an integer array with all Field IDs we want to retrieve, make a call to the DB, print out the values, set another field with a value and save it again. Again, no things like:
entry.setEntryItems(entryItems);
entry.store();
Where we had to set an EntryItems object and fill it with Field IDs and Values separate, we now go to the Entry object, and specify where to save it.
There’s a whole lot more to this API than I said here in this small article, unfortunately I don’t have too much time explore it all at the moment. Once I start writing more applications with it I’m sure other new functions and possibilities show up.
Conclusion
A great step forward for the ARS Java API. Of course it is never fun to break backwards compatibility with version 7.0 and earlier, but at of course those applications will still run with the old libraries against a 7.1 server. If you start writing a new Java application and use the 7.1 API you’ll never want to return the old one.
Full source code with comments download (click)
7.1, arsystem, java, new in 7.1
7.1, api, ars, java
Recent Comments