How to use the Web Service API with Axis 1.4

From Intrument Element Wiki

Jump to: navigation, search

In this page we will show you how to build a java client that uses the Web Service APIs. We will connect to an Instrument Element and retrieve the value of a Parameter exposed by an Instrument Manager. Client side, we will use the Java version of Axis 1.4. If you are completely new to Axis,look in our Technical_Background page for some useful pointers.



Let's start with the libraries you need to include in your program:

  • axis.jar:activation.jar
  • axis-ant.jar:
  • commons-discovery-0.2.jar
  • wsdl4j-1.5.1.jar
  • log4j-1.2.8.jar

If you are wondering where you can get them easily, look at our repository at the following link: lib for run a WS client

Build the Stubs

Now you need to build the stubs for accessing the Web Service. You can do this in two different ways:

Write the Code

We can finally start to write a few lines of code! We will use the Java stubs generated from the Instrument Element WSDL. Refer to the WSDL JavaDoc for a complete guide to the methods we are going to use.

First, we need to build a proxy for the Web Service using the following code:

	private void prepareStub(String endPoint) throws ServiceException {
		System.out.println("Instanciating Instrument Element Service");
		InstrumentElementWSServiceLocator service = new InstrumentElementWSServiceLocator();
			ie = (IEServiceSoapBindingStub)service.getIEService();

Note that the parameter endPoint is a URL that represents the entry point of your service. (An example could be: http://localhost:8080/tinyIE-v1.0.1/services/IEService.)

We will now prepare a few configuration parameters that belong to the particular Instrument you want to contact.

                //the Service End point
                //If your Instrument Element has accounting you probably are going to put ID and pwd. 
                //In most cases you can just have empty strings. 

                // IMUniqueID is the default value of an instrument ID. It should be used if only one Instrument Manager is contained in the IE.
                //Name of the parameter that you want to retrieve inside the instrument
		myTestPlugin.ParameterName="User CPU Usage";

In the Main, we prepare a vector containing the list of names of parameters that we plan to retrieve:

                //This is the list of parameters that we want to retrieve:
		InstrumentManagerParameter[] myPar=new InstrumentManagerParameter[1];
		myPar[0]=new InstrumentManagerParameter();
		myPar[0].setName("Name of the parameter that I want to retrieve");
                //This is where we are going to put the results: 
		InstrumentManagerParameter[] retrievedParameter=null;

We now have to name a function that will contact the web service and do all the jobs (the details of this function will follow).

		try {
		} catch (RemoteException e) {
			System.out.println("Communication Failure accessing the instrument with: EndPoint: "+myTestPlugin.EndPoint+" UserID: "+myTestPlugin.UserID+ " UserPWD: "+myTestPlugin.UserPWD+" InstrumentID: "+myTestPlugin.InstrumentID+ " ParameterName: "+myPar[0].getName());

We are almost done. We now have to check whether or not we have really retrieved a parameter. If the vector is empty, the contacted Instrument does not contain the wanted parameter.

		if (retrievedParameter==null||retrievedParameter.length==0)
			System.out.println("WARN: Parameter Not contained in the Instrument. EndPoint: "+myTestPlugin.EndPoint+" UserID: "+myTestPlugin.UserID+ " UserPWD: "+myTestPlugin.UserPWD+" InstrumentID: "+myTestPlugin.InstrumentID+ " ParameterName: "+myPar[0].getName());
		} else
			System.out.println("Every Thing is OK");

This basically concludes your main setup. What follows is a description of the executeRetrieveParametersValues() function, where we are going to execute all the service calls:

	 * @param endPoint Web Service End Point 
	 * @param sessionID If the Instrument supports accounting, this is the ID.
	 * @param pwd If the Instrument supports accounting, this is the PWD.
	 * @param instrumentID Unique identifier of the Instrument we want to contact. 
	 * @param filter Vector of the parameter we want to retrieve.  If the filter is null, we will retrieve all  
         *                                       parameters in the Instrument.  
	 * @return Vector of parameters that contain the values retrieved from the Instrument itself. 
	 * @throws RemoteException Something went wrong and the parameters were not retrieved. 
private InstrumentManagerParameter[] executeRetrieveParametersValues(String endPoint, String sessionID, String pwd, String instrumentID, InstrumentManagerParameter[] filter) throws RemoteException
		InstrumentManagerParameter[] retPar= null; 
		//Let's prepare the stub first.
                Try {
		} catch (ServiceException e) {
			InstrumentElementException excp = new InstrumentElementException();
			excp.setFaultString("Fail to connect on: "+IE_END_POINT+ "  "+e.getMessage());
			throw excp; 
                //Let's contact the Instrument Element and open a session. If the Instrument Element does not 
                //support this functionality, you can leave fake values. 
		String sid=ie.openSession("rcms","123");
		String[] ieList=ie.getAllTopInstrumentManagers(sid);
		if ((ieList==null)||(ieList.length==0))
			// we did not retrieve any instrument. Look in the varius sub-contexts:
			InstrumentElementException excp = new InstrumentElementException();
			excp.setFaultString("No Instruments have been found");
			throw excp; 
		//looking for the right instrument
		String ieIM=null;
		for (int i=0; i<ieList.length; i++)
			if (ieList[i].equals(instrumentID))
		if (ieIM==null)
			// the retrieved instruments do not match the one we specified 
			InstrumentElementException excp = new InstrumentElementException();
			excp.setFaultString("No Instrument with ID "+instrumentID +" have been found");
			throw excp; 
		System.out.println("Instrument Manager with ID "+ieIM +" Retrieved");

                //Let's instantiate the right Instrument by getting an instance 
		System.out.println("Instantiating: IMID: "+ieIM);
		System.out.println("Retrieving specified Attributes on IM: "+ieIM);
                //Let's retrieve the desired parameters. If the filter is null, we will retrieve the all parameters that are in the Instrument. 
		if (filter==null)
			// we want to retrieve all the instrument parameters
			retPar= ie.getAllParameters(sid, ieIM);
		} else {
			retPar= ie.getParameters(sid, ieIM, filter);
		return retPar;

Done! We are now able to contact an Instrument and to retrieve the parameters it contains.

Testing Your Code

If you want to test your code, you can use one of the following end points:

or you may want to consider to install your Instrument Element following this guide:

Personal tools