Author: jochen
Date: Sun Nov 13 14:05:58 2005
New Revision: 343979
URL: http://svn.apache.org/viewcvs?rev=343979&view=rev
Log:
More docs, before going public.
Added:
webservices/xmlrpc/branches/b20050512_streaming/src/site/apt/extensions.apt
Modified:
webservices/xmlrpc/branches/b20050512_streaming/pom.xml
webservices/xmlrpc/branches/b20050512_streaming/src/site/apt/download.apt
webservices/xmlrpc/branches/b20050512_streaming/src/site/site.xml
Modified: webservices/xmlrpc/branches/b20050512_streaming/pom.xml
URL:
http://svn.apache.org/viewcvs/webservices/xmlrpc/branches/b20050512_streaming/pom.xml?rev=343979&r1=343978&r2=343979&view=diff
==============================================================================
--- webservices/xmlrpc/branches/b20050512_streaming/pom.xml (original)
+++ webservices/xmlrpc/branches/b20050512_streaming/pom.xml Sun Nov 13 14:05:58
2005
@@ -189,5 +189,16 @@
</plugin>
</plugins>
</reporting>
+ <distributionManagement>
+ <repository>
+ <id>people.apache.org</id>
+ <name>Jochen's home directory on people.apache.org</name>
+
<url>scp://people.apache.org/home/jochen/public_html/xmlrpc/dist</url>
+ </repository>
+ <site>
+ <id>people.apache.org</id>
+ <name>Jochen's home directory on people.apache.org</name>
+
<url>scp://people.apache.org/home/jochen/public_html/xmlrpc/site</url>
+ </site>
+ </distributionManagement>
</project>
-
Modified:
webservices/xmlrpc/branches/b20050512_streaming/src/site/apt/download.apt
URL:
http://svn.apache.org/viewcvs/webservices/xmlrpc/branches/b20050512_streaming/src/site/apt/download.apt?rev=343979&r1=343978&r2=343979&view=diff
==============================================================================
--- webservices/xmlrpc/branches/b20050512_streaming/src/site/apt/download.apt
(original)
+++ webservices/xmlrpc/branches/b20050512_streaming/src/site/apt/download.apt
Sun Nov 13 14:05:58 2005
@@ -4,8 +4,11 @@
Downloading Apache XML-RPC
- You can download the latest release version from the
- {{{http://www.apache.org/dyn/closer.cgi/ws/xmlrpc/}distribution directory}}.
+ You can download the current version of the streaming branch from a
+ {{{http://people.apache.org/~jochen/xmlrpc/dist/}private distribution
+ directory}}. The latest release version is in the
+ {{{http://www.apache.org/dyn/closer.cgi/ws/xmlrpc/}official
+ distribution directory}}.
Alternatively, you can get the latest code snapshot via
{{{http://svn.apache.org/repos/asf/webservices/xmlrpc}Subversion}}.
Added:
webservices/xmlrpc/branches/b20050512_streaming/src/site/apt/extensions.apt
URL:
http://svn.apache.org/viewcvs/webservices/xmlrpc/branches/b20050512_streaming/src/site/apt/extensions.apt?rev=343979&view=auto
==============================================================================
--- webservices/xmlrpc/branches/b20050512_streaming/src/site/apt/extensions.apt
(added)
+++ webservices/xmlrpc/branches/b20050512_streaming/src/site/apt/extensions.apt
Sun Nov 13 14:05:58 2005
@@ -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.
+
+ The streaming branch 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
Modified: webservices/xmlrpc/branches/b20050512_streaming/src/site/site.xml
URL:
http://svn.apache.org/viewcvs/webservices/xmlrpc/branches/b20050512_streaming/src/site/site.xml?rev=343979&r1=343978&r2=343979&view=diff
==============================================================================
--- webservices/xmlrpc/branches/b20050512_streaming/src/site/site.xml (original)
+++ webservices/xmlrpc/branches/b20050512_streaming/src/site/site.xml Sun Nov
13 14:05:58 2005
@@ -15,6 +15,7 @@
<item name="Overview" href="/index.html"/>
<item name="Client Classes" href="/client.html"/>
<item name="Server Side XML-RPC" href="/server.html"/>
+ <item name="Vendor Extensions" href="/extensions.html"/>
<item name="XML-RPC Types" href="/types.html"/>
<item name="Download" href="/download.html"/>
<item name="FAQ" href="/faq.html"/>
