The APIs

Last updated 29 December 2005

The Java Client API, class MicrocallerJDOM:

This class is very easy to use, in general you only have to create an instance and start to issue calls, see an example:

  MicrocallerJDOM mc = new MicrocallerJDOM();
  mc.call("http://www.anything.com:port/procedure?param=value");
  if (mc.allRigth())
  {
    // Do something useful
  }
  else
  {
    System.out.println("ERROR "+mc.getErrBuf());
  }

In the above example you can see these sentences:

1.- MicrocallerJDOM mc = new MicrocallerJDOM(); Creates a new instance of the object MicrocallerJDOM, it's important to note that you can reuse this object, for example, make a "call", interpret the result and then make another "call" without creating another instance. Be careful, In this case you have to be sure that you don't need the results of the first call anymore.

In an MVC framework, tipically, you must instantiate a new MicrocallerJDOM for each user request to the Controller servlet.

2.- mc.call("http://www.anything.com:port/procedure?param=value"); This is the important sentence, issue the call to the server, in this sentence the server have to do its job, and return the XML, the call is sync.

When the instance mc receives the XML he proceeds automatically to parse the result and store some contents in internal variables. This is all done in the same statement

3.- if (mc.allRigth()) This condition checks whethever the call has gone well or not, simply evaluate the attribute value of the result tag, if it's OK then the call went allRigth else (ERROR) something goes wrong in the server side.

Note that if the XML is not well formed or there is any parsing problem of the result, the call allRigth will return false and an error message can be found with the call mc.getErrBuf

Note too, that the status of OK or ERROR is set by the server and usually you have control of the meaning and the severity of the error. Sometimes, maybe you only want to indicate with ERROR some special condition. It's up to you.

4.- System.out.println("ERROR "+mc.getErrBuf()); mc.getErrBuf() returns an Error String, explaining the Error returned by the server or exceptionally the problem with the parsing of the response. For example, if there is no connection between the client and the server, you can get a default error message indicating such event.

Usually, however, the ERROR (and its associated message) is set at the server level and indicates some special condition that must be processed by the client.

OK, let's see what else we can do with a Microcall, assume that you have an instance created, named mc, and you already have issued a valid "call" statement:

Start Debuging:

public void setDebugOn(PrintStream p_out)

mc.setDebugOn(System.out);

From now on your microcaller instance will start to write debug information to the standard output. The default debugging state on creation of a new microcaller instance is off.

Stop Debugging:

public void setDebugOff()

mc.setDebugOff();

Stop throwing debug output, it has no effect if it's called when the debug is already off.

Check the returning code:

public int getIntReturnCode ()

l_ret=mc.getIntReturnCode();
if (l_ret>0)
...

Additionally to the value OK or ERROR, you can use the retcode to return an integer value to the client, check-it with this statement and take actions in the client part depending of the returned server value.

public long getLonReturnCode ()

It's the same as getIntReturnCode but with longs, use it whenever the returning code can be very big.

public String getStringReturnCode ()

Use this to avoid convertions from int to String in the returning value.

Check the procedure:

public String getProcedure()

l_proc=mc.getProcedure();
System.out.println("Procedure called: "+l_proc);

In the event you don't know what you are calling, use this statement, simply takes out the "procedure" attribute of the result, its given more for completness that for its usefulness.

Check for a content existence:

public boolean existsContent ()
public boolean existsContent (String p_name)

if (mc.existsContent())
if (mc.existsContent("left"))

In the first case, it checks whenever the content named "default" exists. In the second statement we can check for any content name for existence.

Check for a content content/type:

public String getContentType ()
public String getContentType (String p_name)

String l_type=mc.getContentType();
String l_type=mc.getContentType("left");

Checks the content/type of a given content, remember that supported contentypes are "text/html", "text/plain" and "text/xml"

Check the content transformation:

public String getContentTransformation ()
public String getContentTransformation (String p_name)

String l_trans = mc.getContentTransformation();
String l_trans = mc.getContentTransformation("left");

Returns the URL of the default transformation of a given content, remember that the only useful value of the attribute "transformation" is for contents of type "text/xml" and it must contain the URL to an XSLT file that is able to transform the XML value of the content.

Loop through contents:

public Enumeration getContents()

Enumeration l_enum = mc.getContents();
while (l_enum.hasMoreElements())
{
  String l_name=l_enum.next();
  System.out.println(mc.getContent(l_name));
}

Returns a list of valid "keys" to the content, that is, a list of valid content names.

Finally, get Content values:

public String getContent ()
public String getContent (String p_name)

System.out.println(mc.getContent());
System.out.println(mc.getContent("left"));

getContent returns a String with the text-value of the given content, remember that its more useful in "text/plain" and "text/html" contents, for "text/xml" contents consider using the getTransformedContent call.

Get the content, previusly transformed:

public String getTransformedContent ()
public String getTransformedContent (String p_name, String p_xsl)

String l_transformed=mc.getTransformedContent();
String l_transformed=mc.getTransformedContent("xml1");
String l_transformed=mc.getTransformedContent("xml1", "http://www.microcalls.org/special.xsl");

This method takes the content given and applies the default transformation or (as in the third example) the transformation passed as parameter.

This method only have sense in an "text/xml" content and you have to be aware that it takes the text value of the content as an XML and try to apply an XSLT transformation indicated in the URL (p_xsl or the content's default).

Manipulate the microcall as a whole:

public String getAllTransformed(String urlXSL)

You can call this method if you want to apply an XSLT to the whole resulting call from the server, is more intended for debugging purposes. public String getAllTransformed(String urlXSL, String p_parser_xml, String p_parser_xsl) The same as above, but you can override the xml and xsl parser to be used, the defaults are "org.apache.xerces.jaxp.DocumentBuilderFactoryImpl" and "org.apache.xalan.processor.TransformerFactoryImpl"

public String getAll()

Gets the resulting XML tree returned from the server as an String, is more intended for debugging purposes.

public Document getXML()

Returns a Document object containing the server XML response, is more intended for debugging purposes.

public String toHTML ()

Returns a String explaining the information returned by the call, formated in simple HTML, is more intended for debugging purposes.

public String toString ()

Returns a String explaining the information returned by the call, is more intended for debugging purposes.

Different types of calls:

public Document callGET(String p_url)
public Document callPOST(String p_url)
public synchronized void call(String p_url)

The method call, by default, issues a POST request to the server, it's done in this way to avoid URL length limitations.

Usually, you don't have to worry about this and simply use the method call, but, in some situations (webservers only allowing GET method, for example) it's good to have the possibility of issue a call using GET, in such situtions you can use callGET.