AMT and Java (JAX-WS method)

AMT, SOAP and WSDL

AMT is a management technology from Intel. You can control AMT via SOAP messages over the network and the SOAP messages structure is defined in WSDL files (see the WSDL file attached).

When you develop a software interacting with SOAP web services, you typically don't write XML yourself. It's more interesting to give the WSDL descriptor to a web service stack and let him do the interface between an object oriented method calls and XML messages. Less coding, more automation thanks to descriptors.

You may want to check the previous article on SOAP and WSDL for AMT.

Java

If you want to work with WSDL in Java, in the past you could have used AXIS from the Apache project. But nowadays it's probably a good idea to use Java API for XML Web Services "JSR 224" (a JSR is a standard in the java world). JAX-WS is the reference implementation for JSR 224 (jax-ws.dev.java.net).

If you work with the Sun JVM, it's included in recent versions. In this post I'll work with the Sun JDK 1.6.0.14. In the past all the SOAP stuff was in the Java Enterprise development kit, but now it's standardized and included in the client JVM/SDK.

Remember that in our case the server side is in fact the AMT aware laptop or desktop itself, on the hardware level. All we need to do is create a SOAP client.

Logistics

You don't have to run the sample codes to read this post, but I've created a few simple codes to let you experiment.
The main code is attached to this post or available with syntax coloring from the SVN browser, and the complete environment is available on javaintelamt.sf.net in case you use SVN :

svn co https://javaintelamt.svn.sourceforge.net/svnroot/javaintelamt javaintelamt

Or as a simple zip file if you don't : javaintelamt_softwareblogs_1.0.zip

Note : you'll find more codes on the javaintelamt.sf.net SVN server in the future as it's an evolving project.
So please download the zip, unzip it and read the (short) REAME.txt. You need "ant" and "java" in your path (I am using version 1.6). Ant is like make in the java world, it helps a LOT.

WSDL to Java

So we have a WSDL file, but we want to code with java objects. To generate automatically the .java (and .class) files we have a tool called wsimport in the Java SDK. You could run it as a stand alone command line tool, but it's easier to use it from ant. There's an ant task for it in the webservices jars, we just need to use a taskdef to be able to use it :

<target name="wsimport">

<taskdef name="wsimport" classname="com.sun.tools.ws.ant.WsImport">
<classpath refid="classpath" />
</taskdef>

<wsimport debug="true" verbose="true" keep="true"
destdir="tmp/gen" package="${wsimport.package}.remotecontrol"
wsdl="WSDL/RemoteControlInterface.wsdl" />

</target>

If you launch "ant wsimport" you should see 2 steps : first the generation of .java files, then the compilation. Everything will be available from a java top package, in my case "eu.guermonprez.paul.oss.iamt.wsimport.remotecontrol".
You can look at the generated files in "tmp/gen/eu/guermonprez/paul/oss/iamt/wsimport/remotecontrol/"

Hello AMT World : Basics

Let's create a simple software to reboot a remote machine :
"src/eu/guermonprez/paul/oss/iamt/HelloAMT.java" (also attached to this post and available with syntax coloring).

If you look at the headers, I had to import a "Service" and a "SoapPortType" from the generated files.

SOAP messages are sent via a simple socket, but protected with a "digest" Authentication (just like a regular password protected website). So i defined the default Authenticator with my login/password :

Authenticator.setDefault(new DigestAuthenticator(login, password));

Hello AMT World : Service and Port

We need to instantiate a service first. The service main utility will be to create a SOAP port.

RemoteControlService service = new RemoteControlService();
RemoteControlSoapPortType rcPort =
(RemoteControlSoapPortType) service.getRemoteControlSoapPort();

The term SOAP port may be misleading, as it's not a port as in "port 80 for web service". A SOAP port is a definition of a web service instance.

With "getRemoteControlSoapPort" we had a definition but no parameters, nothing was sent over the network.
We need to provide the hostname and port number for the rcPort. Why such a strange line to define something that important you may wonder ? Well the typical deployment model of web services is to configure the server name in a XML file or via an enterprise directory. The server is usually the place where you got your preconfigured client application from, over the network.
In AMT it's different, each AMT machine is a web server receiving SOAP messages, so we have to define the server hostname at runtime. Possible of course but not very nice. Port by default is 16992.

((BindingProvider) rcPort).getRequestContext().put(
BindingProvider.ENDPOINT_ADDRESS_PROPERTY,
"http://" + host + ":" + port + "/RemoteControlService");

You rcPort is now fully configured and ready to launch remote calls over SOAP.

Hello AMT World : Holders ?

We are executing remote procedure calls ("RPC") over SOAP. It may look like a regular method calls, but it's a communication between a Java JVM and a remote web server, not even in Java. So you can't work with objects like a Long in memory. You need to use Holders to carry the value of an object instead.
The procedure is : I know I'll receive a Long for the system power state from my RPC, so I am creating an empty Holder systemPowerState, I give it as as argument to my RPC and the result will be stored in this Holder after the call. You'll access the value with "systemPowerState.value", but it's your job to remember it's a Long and ask for "systemPowerState.value.longValue()".

If you need to give an argument to a RPC expecting nothing in return, a regular variable is enough. That would be the case for "rcPort.remoteControl".

Now you should be able to understand :

Holder<Long> status = new Holder<Long>();
Holder<Long> systemPowerState = new Holder<Long>();

rcPort.getSystemPowerState(status, systemPowerState);

long statusLong = status.value.longValue();
long systemPowerStateLong = systemPowerState.value.longValue();

Hello AMT World : Values ?

System power state 0 means system running, 5 not running. The codes are documented in the SDK documentation or the WSDL itself.
Technical note : If you know how to access the WSDL annotations from Java (I don't), please contact me : paul.guermonprez@intel.com

The status is a return code. 0 is fine, you may see return codes for unsupported methods or unsupported argument.

Run

Make sure you have java and ant in your path, customize the "build.properties" file (see README.txt) and run : "ant wsimport", then "ant run" to compile and launch the "HelloAMT" simple software.
You should see something like :

[java] HelloAMT : Simple software to display the status of Intel AMT aware computers
[java] 
[java] Copyright 2009 Paul Guermonprez paul@guermonprez.eu
[java] GNU Lesser General Public License
[java] 
[java] status : 0
[java] power : 0
[java] host : charcot
[java] login : admin
[java] password : titiTOTO1!
[java] SOAP : JAX-WS RI 2.1.3.1-hudson-749-SNAPSHOT: Stub for http://charcot:16992/RemoteControlService

If you run "ant test", the software launched will be "Test" on the same machine. Test is REBOOTING the AMT machine !

A little further

It's not that complicated don't you think ? But I don't like to work with BindingProvider and Holders, so I created a simple wrapper called "RemoteControl".

The code is even simpler and shorter :

Authenticator.setDefault(new DigestAuthenticator(login, password));

RemoteControl rc = new RemoteControl(host);
rc.bind();
System.out.println("reboot return code = " + rc.resetPowerCycle());

Hope you liked it. More Java codes in the next episode !
Для получения подробной информации о возможностях оптимизации компилятора обратитесь к нашему Уведомлению об оптимизации.