xmlrpc/xdocs/index.xml - turbine-fulcrum-intake - Git at Google

 <?xml version="1.0"?>
 <!--
  Licensed to the Apache Software Foundation (ASF) under one
  or more contributor license agreements.  See the NOTICE file
  distributed with this work for additional information
  regarding copyright ownership.  The ASF licenses this file
  to you under the Apache License, Version 2.0 (the
  "License"); you may not use this file except in compliance
  with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing,
  software distributed under the License is distributed on an
  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  KIND, either express or implied.  See the License for the
  specific language governing permissions and limitations
  under the License.
 -->

 <document>

   <properties>
     <title>XMLRPC component</title>
     <author email="quintonm@bellsouth.net">Quinton McCombs</author>
   </properties>

   <body>

   <section name="Overview">
     <p>
       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.
     </p>
     <p>
       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.
     </p>
     <p>
       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.
     </p>
     <p>
       For more detailed information how the server works and its capabilities,
       visit the <a href="/ws.apache.org/xmlrpc">xlm-rpc project site</a>
     </p>
   </section>

   <section name="Configuration">

     <p>
       First, here is the role configuration.
     </p>

 <source>
 <![CDATA[
   <role
     name="org.apache.fulcrum.xmlrpc.XmlRpcComponent"
     shorthand="XmlRpcComponent"
     default-class="org.apache.fulcrum.xmlrpc.DefaultXmlRpcComponent"/>
 ]]>
 </source>

   <p>
     Now comes the basic configuration of the component.  Here will will
     configure the port and the xml parser to use.
   </p>
 <source>

 <![CDATA[
   <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>
 ]]>
 </source>

   <p>
     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 <i>paranoid</i> mode.
   </p>
   <p>
     To enable the <i>paranoid</i> mode, simply add the following tags
     to your configuration file inside of the <code>XmlRpcComponent</code>
     section.  You will need to modify the IP addresses accordingly.
   </p>

 <source>
 <![CDATA[
   <!-- 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.*"/>
 ]]>
 </source>

   <p>
     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 <code>XmlRpcComponent</code>
     tags.  Of course, you will need to edit the appropriate values
     to match your environment.
   </p>

 <source>
 <![CDATA[
   <!-- 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" />
 ]]>
 </source>

     <p>
       The final part of the configuration is telling the server about your
       handlers.  For information on how to write handlers, refer
       to the <a href="/ws.apache.org/xmlrpc/server.html">
       xml-rpc server docs</a>
     </p>
     <p>
       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.
     </p>

 <source>
 <![CDATA[
   <!-- 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>
 ]]>
 </source>

   </section>

 <section name="Usage">

 <p>
   The following example is taken from the class used to test the
   file transfer features of the XML-RPC service. The <strong>
   org.apache.fulcrum.xmlrpc.util.FileHandlerTest</strong>
   can be found in the CVS repository. Here is how the FileHandler
   might be used:
 </p>

 <source><![CDATA[

 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");
     }
 }

 ]]></source>

 </section>

 </body>
 </document>
	<?xml version="1.0"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	-->

	<document>

	<properties>
	<title>XMLRPC component</title>
	<author email="quintonm@bellsouth.net">Quinton McCombs</author>
	</properties>

	<body>

	<section name="Overview">
	<p>
	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.
	</p>
	<p>
	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.
	</p>
	<p>
	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.
	</p>
	<p>
	For more detailed information how the server works and its capabilities,
	visit the <a href="/ws.apache.org/xmlrpc">xlm-rpc project site</a>
	</p>
	</section>

	<section name="Configuration">

	<p>
	First, here is the role configuration.
	</p>

	<source>
	<![CDATA[
	<role
	name="org.apache.fulcrum.xmlrpc.XmlRpcComponent"
	shorthand="XmlRpcComponent"
	default-class="org.apache.fulcrum.xmlrpc.DefaultXmlRpcComponent"/>
	]]>
	</source>

	<p>
	Now comes the basic configuration of the component. Here will will
	configure the port and the xml parser to use.
	</p>
	<source>

	<![CDATA[
	<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>
	]]>
	</source>

	<p>
	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 <i>paranoid</i> mode.
	</p>
	<p>
	To enable the <i>paranoid</i> mode, simply add the following tags
	to your configuration file inside of the <code>XmlRpcComponent</code>
	section. You will need to modify the IP addresses accordingly.
	</p>

	<source>
	<![CDATA[
	<!-- 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.*"/>
	]]>
	</source>

	<p>
	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 <code>XmlRpcComponent</code>
	tags. Of course, you will need to edit the appropriate values
	to match your environment.
	</p>

	<source>
	<![CDATA[
	<!-- 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" />
	]]>
	</source>

	<p>
	The final part of the configuration is telling the server about your
	handlers. For information on how to write handlers, refer
	to the <a href="/ws.apache.org/xmlrpc/server.html">
	xml-rpc server docs</a>
	</p>
	<p>
	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.
	</p>

	<source>
	<![CDATA[
	<!-- 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>
	]]>
	</source>

	</section>

	<section name="Usage">

	<p>
	The following example is taken from the class used to test the
	file transfer features of the XML-RPC service. The <strong>
	org.apache.fulcrum.xmlrpc.util.FileHandlerTest</strong>
	can be found in the CVS repository. Here is how the FileHandler
	might be used:
	</p>

	<source><![CDATA[

	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");
	}
	}

	]]></source>

	</section>

	</body>
	</document>