This component wraps Apache's XML-RPC library. It is intended to function as an XML-RPC server. It is written for use in Turbine but it can be used in any container compatible with Avalon's ECM container.
You can configure an unlimited number of handlers to process requests. Your handlers can either be true components (configures and initialized by the container) or normal classes. You can also use a combination of both.
The server can be easily configured to accept or deny connections based on the source IP addess. There is also the option to to use HTTPS instead of HTTP for the communications between the client and the server.
For more detailed information how the server works and its capabilities, visit the xlm-rpc project site
First, here is the role configuration.
<role
name="org.apache.fulcrum.xmlrpc.XmlRpcComponent"
shorthand="XmlRpcComponent"
default-class="org.apache.fulcrum.xmlrpc.DefaultXmlRpcComponent"/>
Now comes the basic configuration of the component. Here will will configure the port and the xml parser to use.
<XmlRpcComponent>
<!-- Port on which the XML-RPC server will listen for
incoming connections -->
<port>12345</port>
<!-- Parser implementation to use -->
<parser>org.apache.xerces.parsers.SAXParser</parser>
</XmlRpcComponent>
By default, the server will accept all incoming connections reguardless of the source IP address. If you would like for you server only to accept from certain addresses or deny from some, then you will need to run the server in paranoid mode.
To enable the paranoid mode, simply add the following tags
to your configuration file inside of the XmlRpcComponent
section. You will need to modify the IP addresses accordingly.
<!-- Paranoid mode will allows you to configure specific
client addresses from which connections will be accepted
or denied -->
<paranoid>true</paranoid>
<!-- Clients from which connections will be accepted. This
section has no meaning unless operating in paranoid mode -->
<acceptedClients clientIP="192.168.1.*"/>
<!-- Clients from which connections will be denied. This
section has no meaning unless operating in paranoid mode -->
<deniedClients clientIP="10.1.1.*"/>
<deniedClients clientIP="10.1.2.*"/>
As stated earlier, the server can use HTTPS for its communications.
If you are interested in enabling this feature, add all of the tags
in the example below somewhere between your XmlRpcComponent
tags. Of course, you will need to edit the appropriate values
to match your environment.
<!-- Should the server use a secure protocol for
communications? -->
<secureServer>true</secureServer>
<!-- Secure server options - these only have meaning
when the secure server option is set to true -->
<systemProperty name="java.protocol.handler.pkgs"
value="com.sun.net.ssl.internal.www.protocol" />
<systemProperty name="security.provider"
value="com.sun.net.ssl.internal.ssl.Provider" />
<systemProperty name="security.protocol"
value="TLS" />
<!-- You probabley want to keep you keyStore and
trustStore out of you webapp root -->
<systemProperty name="javax.net.ssl.keyStore"
value="/tmp/keystore" />
<systemProperty name="javax.net.ssl.keyStoreType"
value="jks" />
<systemProperty name="javax.net.ssl.keyStorePassword"
value="password" />
<systemProperty name="javax.net.ssl.trustStoreType"
value="/tmp/truststore" />
<systemProperty name="javax.net.ssl.trustStorePassword"
value="password" />
<systemProperty name="sun.ssl.keymanager.type"
value="SunX509" />
<systemProperty name="sun.ssl.trust.manager.type"
value="SunX509" />
<!-- Set the following values to "all" for debugging -->
<systemProperty name="javax.net.debug"
value="none" />
<systemProperty name="java.security.debug"
value="none" />
The final part of the configuration is telling the server about your handlers. For information on how to write handlers, refer to the xml-rpc server docs
In the example below, I will show two handlers being configured. The first will be a component. The second will be a regular java object.
<!-- Handlers configured to process incoming requests -->
<handlers>
<handler>
<name>MyComponentHandler</name>
<role>com.company.MyComponent</role>
</handler>
<handler>
<name>MyObjectHandler</name>
<class>com.company.MyObject</class>
</handler>
</handlers>
The following example is taken from the class used to test the file transfer features of the XML-RPC service. The org.apache.fulcrum.xmlrpc.util.FileHandlerTest can be found in the CVS repository. Here is how the FileHandler might be used:
public class XmlRpcExample
{
/**
* We will test the following three operations:
*
* 1) Send a file to a remove server
* 2) Get a file from a remote server
* 3) Remove a file to a remove server
*/
public void testOperations() throws Exception
{
/*
* @param serverURL
* @param sourceLocationProperty
* @param sourceFileName
* @param destinationLocationProperty
* @param destinationFileName
*/
FileTransfer.send("http://www.far-away.com:9000/RPC2",
"test.location",
"test.txt",
"test.location",
"test.send");
/*
* @param serverURL
* @param sourceLocationProperty
* @param sourceFileName
* @param destinationLocationProperty
* @param destinationFileName
*/
FileTransfer.get("http://www.far-away.com:9000/RPC2",
"test.location",
"test.txt",
"test.location",
"test.get");
/*
* @param serverURL
* @param sourceLocationProperty
* @param sourceFileName
*/
FileTransfer.remove("http://www.far-away.com:9000/RPC2",
"test.location",
"test.txt");
}
}