Hello World
From ARSWiki
NOTE: This article contains sample API code for versions 7.0 and earlier of the BMC Remedy AR System Server platform.
First we'll start by declaring the package to which our sample API program will belong.
package org.arswiki.arapi.tutorial;
The next step will be to include the classes which comprise the AR System Java API.
import com.remedy.arsys.api.*;
The next line in our program's source code will be the declaration of the class. We're going to name it HelloWorldARS. Technically, we can leave off the extends java.lang.Object portion of the class declaration because all Objects extend java.lang.Object.
package org.arswiki.arapi.tutorial;
import com.remedy.arsys.api.*;
public class HelloWorldARS extends java.lang.Object {
}
For the purposes of this tutorial, we're going to make this a stand-alone Java application, so we'll include the definition of a main() method.
package org.arswiki.arapi.tutorial;
import com.remedy.arsys.api.*;
public class HelloWorldARS extends java.lang.Object {
public static void main(String argv[]) {
}
}
Since our goal as programmers is to make our users' lives easier, perhaps we'll provide some guidance on how to use our nifty HelloWorldARS program. In the code below, we've added a body to the help() method.
package org.arswiki.arapi.tutorial;
import com.remedy.arsys.api.*;
public class HelloWorldARS extends java.lang.Object {
public static void main(String argv[]) {
}
/**
* Command line syntax help
*/
public static void help() {
StringBuilder msg=new StringBuilder(240);
msg.append("HelloWorldARS\n\n");
msg.append("Usage:\n\n");
msg.append("\tjava HelloWorldARS <servername> <username> ");
msg.append("<password>");
System.out.println(msg.toString());
}
}
The final step will be to add the body to the main() method. This method will take the server name, user name and password passed on the command line when the program is invoked and it log into specified AR System Server using the supplied credentials. Once successfully authenticated, the utility will display information from the control structure created as a result of the login() method.
The source code itself is fairly well documented and explains the different steps of the process.
public static void main(String argv[]) {
// Declare the variables that we're going to use in the method.
ARServerUser ctx=null;
String userName=null;
String password=null;
String language="";
String arSystemServer=null;
As a matter of practice and coding style, I tend to declare variables I'm going to use at the beginning of the method declaration. I'll also perform some basic initialization of the declared variables.
The next step will be to check the command line to see if the requisite parameters (server name, user name, and pasword) have been passed.
// Check parameter count to ensure that the user specified the
// appropriate number of parameters.
if (argv.length < 3) {
help(); // Invoke the online help
System.exit(-1); // Terminate the running program
} else {
If the parameters were not displayed, the help() method is invoked and the program terminates. If all three parameters were passed, then we'll assign them to the local variables we've identified at the method declaration.
// Initialize local variables with parameters passed on command line.
arSystemServer=argv[0]; // The first parameter is the server name.
userName=argv[1]; // The second parameter is the user name.
password=argv[2]; // The third parameter is the password.
Using the information passed on the command line, we'll create an instance of the ARServerUser object. This object is essential to every method made to the AR System server because it contains your authentication information.
// Create the AR System "context" structure which is passed to all
// AR System API calls. This structure contains your user ID and
// password information.
ctx=new ARServerUser(userName, password, language, arSystemServer);
There is no need to wrap the instantiation of the ARServerUser object with a try/catch block because it does not throw an exception. This is because there has not yet been an attempt to interact with the AR System server. The next step in our HelloWorld example will be to use the information passed on the command line to authenticate against an AR System server.
/* The remaining commands must be wrapped in a try/catch block to handle an
ARException exception should it be thrown. */
try {
// Log into the AR System server. If this fails, the catch block shown
// below will handle the error code.
ctx.login();
Once successfully authenticated, we'll create a StringBuilder instance which we'll use to build a message block that will output information now contained in the ARServerUser object after logging in.
// After a successful login, print out some general information
// to demonstrate that a connection was indeed established.
StringBuilder msg=new StringBuilder(1024);
// Append the Authentication property from the ctx object
msg.append("Authentication: ").append(ctx.getAuthentication()).append('\n');
msg.append("Admin Flag: ").append(ctx.getAdminFlag()).append('\n');
msg.append("Cache ID: ").append(ctx.getCacheId()).append('\n');
msg.append("Customize Flag: ").append(ctx.getCustomFlag()).append('\n');
msg.append("Language: ").append(ctx.getLanguage()).append('\n');
msg.append("Operation Time: ").append(ctx.getOperationTime()).append('\n');
msg.append("Sub-Admin Flag: ").append(ctx.getSubAdminFlag()).append('\n');
msg.append("Proxy: ").append(ctx.getProxy()).append('\n');
msg.append("Version String: ").append(ctx.getVersionString()).append('\n');
Every call to the AR System server can produce a number of StatusInfo objects. These objects will contain Note, Warning, and Error messages generated by workflow triggered by the API call. The code snippet shown below will display any of the StatusInfo objects returned by the login method.
/* Every AR System API transaction will return a StatusInfo array which contains
any Note, Warning, or Error messages generated during the execution of the
API call.
The following code will display the full contents of the StatusInfo array
returned after execution of the login() method. */
StatusInfo[] si=ctx.getLastStatus();
if (si.length > 0) {
// There is at least one StatusInfo object contained in the array.
System.out.println("Status Info:");
// Go through each element in the StatusInfo array and print the contents.
for (int i=0; i < si.length; i++) {
System.out.println("\tMessage Type: "+si[i].getMessageType());
System.out.println("\tMessage Number: "+si[i].getMessageNum());
System.out.println("\tMessage Text: "+si[i].getMessageText());
} // END for (int i=0; i < si.length; i++)
} // END if (si.length > 0)
After your work with the AR System server is complete, don't forget to log out!
// Log out of the AR System Server
ctx.logout();
If there is some type of a problem authenticating with the AR System server, an ARException object would have been thrown. The code shown below in the catch block prints out the error information.
} catch (com.remedy.arsys.api.ARException ex) {
// Handle any exceptions thrown while interacting with the AR System server.
System.out.println("An ARException was thrown trying to log into the server.");
System.out.println(ex);
}
}
}
