Added: webservices/xmlrpc/trunk/src/site/apt/extensions.apt URL: http://svn.apache.org/viewcvs/webservices/xmlrpc/trunk/src/site/apt/extensions.apt?rev=378632&view=auto ============================================================================== --- webservices/xmlrpc/trunk/src/site/apt/extensions.apt (added) +++ webservices/xmlrpc/trunk/src/site/apt/extensions.apt Fri Feb 17 13:27:38 2006 @@ -0,0 +1,131 @@ + -------------------------------- + Apache XML-RPC Vendor Extensions + -------------------------------- + +Introduction + + The {{{http://www.xmlrpc.com/spec}XML-RPC specification}} has been + published in 1999. In the past 6 years, it was subject to some + minor corrections. Some things have been made clearer. However, it + hasn't really changed or evolved. Dave Winer, the XML-RPC specifications + author, has always rejected any suggestions in that direction. Of course, + he did so with a good reason: One of XML-RPC's major targets was + portability over arbitrary platforms and programming languages. Clearly, + this target has been met and any further development would mean putting + this at risk. + + On the other hand, this is most unfortunate: Obeying the specification + means accepting really serious limitations. For example, one cannot even + use all of Java's primitive data types, although nowadays they have + equivalents in almost any programming language. Possibly even more + important is the requirement to send a content-length header: HTTP/1.1 + and its chunk encoding are the definite standard in 2005 for both HTTP + clients and servers. Consequently, the content-length header is, at + best, superfluos. Of course, having an additional header wouldn't be + too much of a problem. But calculating the header value enforces, that + request and response are written to byte arrays, before actually sending + them. This is both slow and memory consuming. + + Version 3 of Apache XML-RPC is a compromise: By default it + still meets the specification. However, you <<may>> enable additional + features, called vendor extensions. Of course, these features only work, + if you have a streaming version of Apache XML-RPC on both sides. In + practice, it occurs very frequently, that both sides are controlled by + the same people. Besides, the vendor extensions are documented very + clearly here: Adding these features to an existing XML-RPC library + would mean almost no effort, so possibly someone does. You'r welcome. + + But the purpose of this document is more than documentation: It is also + to receive feedback and discuss the extensions specification and + implementation. Nothing is fixed, and everything can be changed. + +Enabling extensions + + Vendor extensions cannot be used, unless they are explicitly enabled. + In some cases, you have to enable specific features, for example + request compression. But in all cases, you need to enable the use + of vendor extensions at all, because that is the step, where you + knowingly say: "I know, I am now in violation of the original XML-RPC + specification." + + For that reasons, both server and client have a property + <<<enabledForExtensions>>> in their respective configuration. Setting + this property to true enables the extensions. + +Streaming Mode + + Putting the client or the server into streaming mode means, that + data being sent to the other side is almost directly written to + the network connection. (Besides, of course, using a moderately + sized <<<BufferedOutputStream>>>, because one would not want to + have a network connection for any <<<write()>>> call.) + + In particular, the request, or response, isn't written to a + <<<ByteArrayOutputStream>>> internally. Without streaming mode, + this is always the case. But there is more: For example, the + base64 encoder is also writing directly without internal buffering. + (There are few other base64 encoders around, which support streaming + mode.) + + To enable streaming mode on the client, set the properties + <<<enabledForExtensions>>> and <<<contentLengthOptional>>>. This + will take care for the request, which is being sent to the server. + + On the server, things are a little bit more complicated. Currently, + the server behaves as follows: If streaming mode is disabled, then + the server will always behave like a standard XML-RPC server. + Otherwise, the server will verify, whether the client sends a + content-length header. If so, then the server assumes that the + client is able to accept a missing content-length header in the + response as well. Otherwise, the server will still disable streaming + for this particular requests. In other words, traditional clients + will still receive a traditional response and one server can serve + both data types. + +Compression + + HTTP Request compression is a standard HTTP feature and works by + using the HTTP headers <<<Accept-Encoding>>> and <<<Content-Encoding>>>. + In other words, it is quite likely, that request compression is + supported by your HTTP client or server library. For example, the + Apache httpd does so by using the <<<mod_deflate>>> module. + + Of course, it's more convenient to have the XML-RPC library doing + this. If the client should compress the response, then you need + to set the properties <<<enabledForExtensions>>> and + <<<gzipCompressing>>>. The XML-RPC request will be compressed + (on-the-fly in streaming mode, of course) and the HTTP header + <<<Content-Encoding>>> will be set to <<<gzip>>>. Needless to say, + you may only do so, if the server is ready to accept such requests. + + Compressing the request doesn't mean that the response is compressed + as well. First of all, the server will only send a compressed response, + if the server property <<<enabledForExtensions>>> is set. Additionally, + the server will read the HTTP header <<<Accept-Encoding>>>: If it + doesn't contain <<<gzip>>> encoding, then compression cannot take + place. In other words, the client must send this header. You need + to set the client properties <<<enabledForCompression>>> and + <<<gzipRequesting>>> to achieve that. + +Data Types + + Enabling vendor extensions means also, that several additional + data types may be sent. (See {{{./types.html}Data Types}} for + details.) These different data types require an extension of the + XML-RPC network protocol. + + All of these data types are using a special XML namespace. Using this + namespace is a clear indication, that these data types are in violation + to the XML-RPC specification. + + For example, sending an integer value looks like the following: +---------------------------------------------------------------------------- + <i4>347</i4> +---------------------------------------------------------------------------- + 32 bit integers are valid data types in XML-RPC. So we do not need + to use a separate namespace here. 64 bit integers aren't valid XML-RPC + data types. So we need to use our namespace when sending them: +---------------------------------------------------------------------------- + <i8 xmlns="http://ws.apache.org/xmlrpc/namespaces/extensions";>78934</i8> +---------------------------------------------------------------------------- + \ No newline at end of file
Added: webservices/xmlrpc/trunk/src/site/apt/index.apt URL: http://svn.apache.org/viewcvs/webservices/xmlrpc/trunk/src/site/apt/index.apt?rev=378632&view=auto ============================================================================== --- webservices/xmlrpc/trunk/src/site/apt/index.apt (added) +++ webservices/xmlrpc/trunk/src/site/apt/index.apt Fri Feb 17 13:27:38 2006 @@ -0,0 +1,24 @@ + -------------- + Apache XML-RPC + -------------- + +About Apache XML-RPC + + Apache XML-RPC is a Java implementation of + {{{http://www.xmlrpc.com/}XML-RPC}}, a popular protocol that + uses XML over HTTP to implement remote procedure calls. + + Version 3 of Apache XML-RPC is still compliant to the + {{{http://www.xmlrpc.com/spec}XML-RPC specification}}. + However, the user may enable several vendor extensions + are available, that greatly extend the power of XML-RPC: + + * All primitive Java types are supported, including long, + byte, short, and double. + + * DOM nodes, or JAXB objects, can be transmitted. So are + objects implementing the java.io.Serializable interface. + + * Both server and client can operate in a streaming mode, + which preserves resources much better than the default + mode, which is based on large internal byte arrays. Added: webservices/xmlrpc/trunk/src/site/apt/server.apt URL: http://svn.apache.org/viewcvs/webservices/xmlrpc/trunk/src/site/apt/server.apt?rev=378632&view=auto ============================================================================== --- webservices/xmlrpc/trunk/src/site/apt/server.apt (added) +++ webservices/xmlrpc/trunk/src/site/apt/server.apt Fri Feb 17 13:27:38 2006 @@ -0,0 +1,104 @@ + ------------------------- + The Apache XML-RPC Server + ------------------------- + + +Server-side XML-RPC + + If you have read and understood the previous document about the + {{{./client.html}Apache XML-RPC client}}, then the server isn't too + much news. + + First of all, there is an object, called the XmlRpcServer. This objects + purpose is to receive and execute XML-RPC calls by the clients. The + XmlRpcServer <<can>> be embedded into a servlet container, or another + HTTP server (for example, the minimal web server, that comes with + XML-RPC), but it doesn't need to. Take the local transport as an + example: In that case the XML-RPC server is simply embedded into the + client application. + + Like the XmlRpcClient, the XmlRpcServer needs a configuration, which + is given by the XmlRpcServerConfigImpl object. + +The XML-RPC Servlet + + The easiest of creating an XML-RPC Server is the XmlRpcServlet. This + servlet allows you to create a server within 10 minutes or so: + + [[1]] Create a class, or a set of classes, which are implementing + the remote procedure calls. Here's an example of such a class: + +----------------------------------------------------------------------------------- + package org.apache.xmlrpc.demo; + public class Calculator { + public int add(int i1, int i2) { + return i1 + i2; + } + public int subtract(int i1, int i2) { + return i1 - i2; + } + } +----------------------------------------------------------------------------------- + + This class has two public, non-static methods, which should + be available to the clients. The only important thing to + consider is: The class must be stateless. In other words, + it must not contain any non-final fields. (The same restriction + applies, for example, to servlet classes.) + + [[2]] Create a property file, which contains at least one property. + The property name is arbitrary, and the property value is the + fully qualified name of the Calculator class. For example, like + that: + +----------------------------------------------------------------------------------- + Calculator=org.apache.xmlrpc.demo.Calculator +----------------------------------------------------------------------------------- + + The property file must be called <<<XmlRpcServlet.properties>>>, + and it must be located in the package org.apache.xmlrpc.webserver. + In other words, you would typically put it into the directory + org/apache/xmlrpc/webserver and add it to your jar file. + + [[3]] Add entries like the following to your war files web.xml: + +----------------------------------------------------------------------------------- + <servlet> + <servlet-name>XmlRpcServlet</servlet-name> + <servlet-class>org.apache.xmlrpc.webserver.XmlRpcServlet</servlet-class> + </servlet> + <servlet-mapping> + <servlet-name>XmlRpcServlet</servlet-name> + <url-pattern>/xmlrpc</url-pattern> + </servlet-mapping> +----------------------------------------------------------------------------------- + + That's it! You have just created your first XML-RPC server. :-) + +The Server configuration + + Unlike in the case of the clients configuration, there isn't much to + configure on the server. The reason is, that most things depend on the + client and the HTTP headers, which are received by the client. There + is one very important property to configure, though: + +*-----------------------+---------------------------------------------------+ +| Property Name | Description | +*-----------------------+---------------------------------------------------+ +| enabledForExtensions | Whether the vendor extensions of Apache XML-RPC | +| | should be enabled. By default, Apache XML-RPC is | +| | strictly compliant to the XML-RPC specification. | +| | | +| | Enabling this property doesn't indicate, that the | +| | server is unable to serve requests by standard | +| | clients: In contrary, the servers behaviour | +| | depends on the client. Setting this property to | +| | true will only advice the server, that it <<may>> | +| | accept requests, which ask for vendor extensions. | +| | | +| | For example, if a client sends a content-length | +| | header, then the server assumes, that the client | +| | <<wants>> a content-length header in the request | +| | and disables the streaming mode. | +*-----------------------+---------------------------------------------------+ + Added: webservices/xmlrpc/trunk/src/site/apt/types.apt URL: http://svn.apache.org/viewcvs/webservices/xmlrpc/trunk/src/site/apt/types.apt?rev=378632&view=auto ============================================================================== --- webservices/xmlrpc/trunk/src/site/apt/types.apt (added) +++ webservices/xmlrpc/trunk/src/site/apt/types.apt Fri Feb 17 13:27:38 2006 @@ -0,0 +1,72 @@ + ------------------ + XML-RPC Data Types + ------------------ + +Data Types + + The {{{http://www.xmlrpc.com/spec}XML-RPC specification}} defines the following + available data types: + +*--------------------+--------------------+-------------------------------------+ +| Java Type | XML Tag Name | Description | +*--------------------+--------------------+-------------------------------------+ +| Integer | <i4>, or | A 32-bit, signed, and non-null, | +| | <int> | integer value. | +*--------------------+--------------------+-------------------------------------+ +| Boolean | <boolean> | A non-null, boolean value (0, or | +| | | 1). | +*--------------------+--------------------+-------------------------------------+ +| String | <string> | A string, non-null. | +*--------------------+--------------------+-------------------------------------+ +| Double | <double> | A signed, non-null, double | +| | | precision, floating point number. | +| | | (64 bit) | +*--------------------+--------------------+-------------------------------------+ +| java.util.Calendar | <dateTime.iso8601> | A pseudo ISO8601 timestamp, like | +| java.util.Date | | 19980717T14:08:55. However, | +| | | compared to a true ISO8601 value, | +| | | milliseconds, and time zone | +| | | informations are missing. | +*--------------------+--------------------+-------------------------------------+ +| byte[] | <base64> | A base64 encoded byte array. | +*--------------------+--------------------+-------------------------------------+ +| java.util.Map | <struct> | A key value pair. The keys are | +| | | strings. The values may be any | +| | | valid data type, including another | +| | | map. | +*--------------------+--------------------+-------------------------------------+ +| Object[] | <array> | An array of objects. The array | +| java.util.List | | elements may be any valid data | +| | | type, including another array. | +*--------------------+--------------------+-------------------------------------+ + + If the property <<<enabledForExtensions>>> is set, then additional data + types become valid. (Both client and server do support this property.) + +*----------------------+--------------------+-------------------------------------+ +| Java Type | XML Tag Name | Description | +*----------------------+--------------------+-------------------------------------+ +| None | <ex:nil> | A typeless null value. | +*----------------------+--------------------+-------------------------------------+ +| Byte | <ex:i1> | A 8-bit, signed, and non-null, | +| | | integer value. | +*----------------------+--------------------+-------------------------------------+ +| Float | <ex:float> | A signed, non-null, double | +| | | precision, floating point number. | +| | | (32 bit) | +*----------------------+--------------------+-------------------------------------+ +| org.w3c.dom.Node | <ex:dom> | A DOM node, which is being | +| | | transmitted as an embedded XML | +| | | fragment. | +*----------------------+--------------------+-------------------------------------+ +| Short | <ex:i2> | A 16-bit, signed, and non-null, | +| | | integer value. | +*----------------------+--------------------+-------------------------------------+ +| java.io.Serializable | <ex:serializable> | An object, which is converted into | +| | | a serialized representation and | +| | | transmitted as a base 64 encoded | +| | | byte array. | +*----------------------+--------------------+-------------------------------------+ + + In the above table, the prefix <<<ex>>> refers to the namespace URI + <<<http://ws.apache.org/xmlrpc/namespaces/extensions>>>. Added: webservices/xmlrpc/trunk/src/site/fml/faq.fml URL: http://svn.apache.org/viewcvs/webservices/xmlrpc/trunk/src/site/fml/faq.fml?rev=378632&view=auto ============================================================================== --- webservices/xmlrpc/trunk/src/site/fml/faq.fml (added) +++ webservices/xmlrpc/trunk/src/site/fml/faq.fml Fri Feb 17 13:27:38 2006 @@ -0,0 +1,80 @@ +<faqs title="FAQ"> + <part id="general"> + <faq id="state"> + <question>What is the state of Apache XML-RPC, version 3?</question> + <answer> + <p>It is alpha software. In other words, it is not yet + sufficiently mature. Most possibly, lots of details + will change in the near future. Give it a try, if + you like, but do not expect to use it without + modifications in the medium term.</p> + </answer> + </faq> + </part> + + <part id="client"> + <faq id="compression_request"> + <question>How do I enable request compression?</question> + <answer> + <p>That's simple: Set the properties "enabledForExtensions" + and "gzipCompressing". That said, note the following + hints:</p> + <ul> + <li>Setting these properties will only work, if the XML-RPC + server is aware of request compression. Compression is a + violation of the XML-RPC specification, so typically the + server will refuse the request, unless it is an Apache + XML-RPC server with version 2 or later. (Apache XML-RPC 2 + supports request compression, although it was officially + designed to be strictly compliant to the XML-RPC specification. + However, noone was aware, that compression violates the + specification. :-)</li> + <li>Compressing the request doesn't mean that the response + will also be compressed. You need to request response + compression to achieve that.</li> + </ul> + </answer> + </faq> + + <faq id="compression_response"> + <question>How do I enable response compression?</question> + <answer> + <p>That's as simple as enabling request compression: Set the + properties "enabledForExtensions" and "gzipRequesting". + That said, note the following hints:</p> + <ul> + <li>Requesting gzip compression is a standard HTTP feature. + In other words, you may safely request compression from + any XML-RPC server, even if it doesn't run Apache XML-RPC. + </li> + <li>However, requesting compression doesn't necessarily mean, + that the response *is* compressed. It depends on the server.</li> + </ul> + </answer> + </faq> + </part> + + <part id="server"> + <faq id="streaming_mode"> + <question>How do I enable streaming mode?</question> + <answer> + <p>Set the property "enabledForExtensions". Note, that enabling + the streaming mode doesn't mean, that all responses are served + in streaming mode. It depends on the clients:</p> + <ul> + <li>If a client sends a content-length header, then the server + assumes, that the client is a traditional XML-RPC application + and doesn't support the vendor extensions from Apache XML-RPC. + Consequently, the server assumes, that it needs to set the + content-length header itself and disables the streaming mode + for that particular request.</li> + <li>However, if the client doesn't send a content-length header, + then the server assumes that it will be able to accept any + standard HTTP/1.1 request and enable the streaming mode. + Streaming mode means, in particular, that the response will + not contain a content-length header.</li> + </ul> + </answer> + </faq> + </part> +</faqs>
