|
| Home | APIS | Download | License | History | Contributors |
Last updated 29 December 2005
In those days the so-called "web programming" implies a lot of plumbing and is an error-prone process.
Different technologies are trying to emerge in this environment, to help programmers in this daily semi-artistic and semi-plumbing job.
I'm referring to XML-RPC and WebServices over SOAP.
The typical approach, adopted by those technologies is to introduce a lot more of plumbing in an inner level, relaying on modern IDEs that generate automatically this level of abstraction.
That's a problem, you have to relay yourself in a IDE and leave the precious paradigm of notepad-vi programming.
Additionally, those technologies are too complex and too general. Usually you don't need such power and you are wasting scarce memory and processing resources at each use.
Don't misunderstand me, I'm not trying to substitute any of those or any future technologies, of course they are standards driven by powerful companies and organizations.
What I'm trying to expose is that a simple, in fact very very simple technology like microcalls, can save the day in 90% of the daily plumbing routine of a web programmer.
Please, if you don't find the functionality you require in a given point of your application, don't blame microcalls (and don't blame me) simply use another and more powerful technology as the ones listed before.
A microcall is only an XML-dialect used to communicate a Client and a Server in a standard and easy-to-use way.
The client part (usually) is implemented in java and consists in a simple POJO that can understand the XML messages returned by the server responding to a given call.
The server part is, in fact, only responsible to return standard and correct messages in response to a given call (in fact a URL with or without parameters).
Of course the server usually does a lot of work when receives a call (for example insert a record in the database) but, from the client standpoint, the server only returns a message "explaining" the result of the call.
The security of the microcalls is based in the protocols in which relays, for example, use a firewall to accept only microcalls from a given server, use HTTPS instead of HTTP to make encrypted calls, etc. In general, don't reinvent the wheel.
For example, you have an Oracle Database with an embedded webserver, let's say in port 7777, then you can let the different front-end server access the database server in the firewall configuration, and forbid the use of this IP:port from anywhere else.
Let's see the protocol by example, I'm going to show you some examples, from a very easy to a relatively more complex one:
This is the simplest microcall response to a call
<result procedure="test1" value="OK" retcode="0"/>
The document root of a microcall is always "result", result always have the attributes "procedure", "value" and "retcode". The procedure is a String with the name of the procedure being called The value can take two possible values "OK" or "ERROR" And the retcode is an integer indicating some returning state (for example, return the number of rows inserted or simply a flag UNIX style 0=OK -1=ERROR, whatever you like)
The second most simple response is an ERROR
<result procedure="test1" value="ERROR" retcode="-1" errbuf="Error in update."/>
Here you can see the same procedure attribute, the same value attribute (this time with "ERROR" instead of "OK" value) a retcode with value -1 (in this you can put whatever value you like) and a new attribute errbuf. In errbuf you can set a message, usually, human-readable, to return to the client.
Lets do more funny things...
<result procedure="test1" value="OK" retcode="0"> <content name="default" type="text/html"><![CDATA[This is an html content with <b>tags</b> inside, the content doesn't need to be well formed XML, for example you can use <br> without closing it, however this is not recomended, only note that is possible.]]></content> </result>
In this result, you can see a similar response as in Result 1 but, in this case you return some HTML chunk, that can be used by your front-end system.
The new entity is "content", you can use any number of contents as child of the result entity.
The content entity has 2 or 3 attributes, lets describe the two in the example above:
name, can be any name, but "default" is an special name, if you use default the client can do a call String l_content = mc.getContent() without parameters and obtain the text value of the content named "default", in this example l_content will contain "This is an html content with tags inside, the content doesn't need to be well formed XML, for example you can use
without closing it, however this is not recommended, only note that is possible."
type, this attribute indicates the "Content/Type" of the text inside the content, it can be "text/html" or "text/plain" or "text/xml" In the case of "text/html" or "text/plain" always surround the text value inside a CDATA section, in the case of text/xml its not needed as long as you return well formed xml inside the text value.
Let's see a couple more of content returns:
<result procedure="test1" value="OK" retcode="0"> <content name="left" type="text/html"><![CDATA[<ul><li>Item 1</li><li>Item 2</li></ul>]]></content> <content name="center" type="text/html"><![CDATA[This is an html content with <b>tags</b> inside, the content doesn't need to be well formed XML, for example you can use <br> without closing it, however this is not recomended, only note that is possible.]]></content> </result>
In this example we return 2 contents, one with the name "left" is a chunk of html intended to show a list of items, the other, named "center" is another chunk of html, in the client side you can access the two contents with calls like
String l_left=mc.getContent("left");
String l_center=mc.getContent("center");
Another more complex way of returning things from a microcall is returning XML and transforming it via XSL, its integrated in the Microcaller Parser, so its very easy to do, let's see an example:
<result procedure="test1" value="OK" retcode="0">
<content name="left" type="text/html"><![CDATA[<ul><li>Item 1</li><li>Item 2</li></ul>]]></content>
<content name="center" type="text/html"><![CDATA[This is an html content with <b>tags</b>
inside, the content doesn't need to be well formed XML, for example you can use <br>
without closing it, however this is not recommended, only note that is possible.]]></content>
<content name="xml1" type="text/xml" transformation="http://www.microcalls.org/sample.xsl">
<rows>
<row number="1">aaa@aa.com</row>
<row number="2">bbb@bb.com</row>
<row number="3">ccc@cc.com</row>
</rows>
</content>
</result>
This is one of the most powerful examples, we have the same two contents "left" and "center" as in previous examples, but now, we have a new content called "xml1" (note that you can have any number of contents and they can be heterogeneous), this content (xml1) contains a xml chunk instead of an html o a text plain chunk. Note that we have a new attribute only valid when talking about xml contents, "transformation".
Transformation attribute, as you can have inferred, is used to tell the parser which xsl to use in order to transform the content value, imagine the next call in the client side:
String l_transformed_content = mc.getTransformedContent("xml1");
This will take the xml text inside "xml1" content, and apply the default transformation (http://www.microcalls.org/sample.xsl) to it. The result of the transformation can be for example another html chunk that you can pass through to your View component (for example to a JSP page)
There is another client call, that can override the default transformation:
String l_transformed_content = mc.getTransformedContent("xml1", "http://www.microcalls.org/special.xsl");
The only responsibility of the server part is to interpret the parameters sent by the client, do some job, and return a microcall standard result.
As you see in the protocol examples, it' s very easy to forge result messages in a standard fashion.
In the downloads section you can take a look at different server-helper code to generate the messages, easely and without errors.
The client have two responsibilities, first it must make the call to the server and second it must interpret the result returned.
In some special cases the client is only capable of issue the call and it doesn't care about the result, think about a shell script that makes a wget call to update some status in the database, but the language doesn't care about the result. This can be dangerous, for example, if the server gets errors as result to the call, but sometimes is difficult and not cost-effective to interpret the results in a shell script.
Let's see an example of a typical client interaction, we assume the microcall will return as in the above example "Result 5":
MicrocallerJDOM mc = new MicrocallerJDOM();
mc.call("http://www.microcalls.org/test1.xml");
if (mc.allRigth())
{
String l_left = mc.getContent("left");
String l_center= mc.getContent("center");
String l_trans = mc.getTransformedContent("xml1");
request.setAttribute("left", l_left);
request.setAttribute("center", l_center);
request.setAttribute("trans", l_trans);
/* Here you can forward to the view JSP with the attributes set */
...
}
else
{
System.out.println("Unexpected Microcall error: "+mc.getErrBuf());
}
You can download the POJO class MicrocallerJDOM and play with it, you can discover a lot of more functionalities, I will talk about it in future documents.