org.apache.xmlrpc
Class XmlRpc

java.lang.Object
  org.xml.sax.HandlerBase
      org.apache.xmlrpc.XmlRpc

All Implemented Interfaces:

DocumentHandler, DTDHandler, EntityResolver, ErrorHandler

Direct Known Subclasses:

XmlRpcClientResponseProcessor, XmlRpcRequestProcessor

public abstract class XmlRpc
extends HandlerBase

This abstract base class provides basic capabilities for XML-RPC, like parsing of parameters or encoding Java objects into XML-RPC format. Any XML parser with a SAX interface can be used.

XmlRpcServer and XmlRpcClient are the classes that actually implement an XML-RPC server and client.

Version:

$Id: XmlRpc.html 359531 2005-12-28 13:59:25Z jochen $

Author:

Hannes Wallnoefer, Daniel L. Rall, Andrew Evers

See Also:

XmlRpcServer, XmlRpcClient

Nested Class Summary

(package private) class

XmlRpc.Value This represents a XML-RPC value parsed from the request.

Field Summary

(package private) static int	ARRAY
(package private) static int	BASE64
(package private) static int	BOOLEAN
(package private) java.lang.StringBuffer	cdata Used to collect character data (CDATA) of parameter values.
(package private) XmlRpc.Value	currentValue
(package private) static int	DATE
static boolean	debug Whether to log debugging output.
(package private) static java.lang.String	defaultInputEncoding Java's name for the input encoding we're using.
(package private) static int	DOUBLE
(package private) static java.lang.String	encoding Java's name for the encoding we're using.
(package private) int	errorLevel
(package private) java.lang.String	errorMsg
(package private) static int	FATAL
(package private) static int	INTEGER
(package private) static boolean	keepalive Wheter to use HTTP Keep-Alive headers.
(package private) java.lang.String	methodName
(package private) static int	NONE
(package private) boolean	readCdata
(package private) static int	RECOVERABLE
(package private) static int	STRING
(package private) static int	STRUCT
(package private) static java.lang.String[]	types The list of valid XML elements used for RPC.
(package private) java.util.TimeZone	tz
(package private) java.util.Stack	values
static java.lang.String	version The version string used in HTTP communication.

Constructor Summary

protected	XmlRpc() Creates a new instance with the TypeFactory set to an instance of the class named by the org.apache.xmlrpc.TypeFactory System property.
protected	XmlRpc(java.lang.String typeFactoryName) Creates a new instance with the specified TypeFactory.

Method Summary

void	characters(char[] ch, int start, int length) Method called by SAX driver.
void	endElement(java.lang.String name) Method called by SAX driver.
void	error(SAXParseException e) Receive notification of a recoverable parser error.
void	fatalError(SAXParseException e) Report a fatal XML parsing error.
static java.lang.String	getDefaultInputEncoding() Return the default input encoding.
java.lang.String	getEncoding() Return the encoding, transforming to the canonical name if possible.
java.lang.String	getInputEncoding() Get the input encoding for this XmlRpc instance.
static boolean	getKeepAlive() get current HTTP keepalive mode.
static int	getMaxThreads() Gets the maximum number of threads used at any given moment.
(package private) java.util.TimeZone	getServerTimeZone()
protected abstract void	objectParsed(java.lang.Object what) This method is called when a root level object has been parsed.
(package private) void	parse(java.io.InputStream is) Parse the input stream.
static void	setDebug(boolean val) Switch debugging output on/off.
static void	setDefaultInputEncoding(java.lang.String enc) Set the default input encoding of the XML.
static void	setDriver(java.lang.Class driver) Set the SAX Parser to be used by directly passing the Class object.
static void	setDriver(java.lang.String driver) Set the SAX Parser to be used.
static void	setEncoding(java.lang.String enc) Set the encoding of the XML.
void	setInputEncoding(java.lang.String enc) Set the input encoding for this XmlRpc instance.
static void	setKeepAlive(boolean val) Switch HTTP keepalive on/off.
static void	setMaxThreads(int maxThreads) Sets the maximum number of threads used at any given moment.
(package private) void	setServerTimeZone(java.util.TimeZone z)
void	startElement(java.lang.String name, AttributeList atts) Method called by SAX driver.

Methods inherited from class org.xml.sax.HandlerBase

endDocument, ignorableWhitespace, notationDecl, processingInstruction, resolveEntity, setDocumentLocator, startDocument, unparsedEntityDecl, warning

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

version

public static final java.lang.String version

The version string used in HTTP communication.

See Also:

Constant Field Values

methodName

java.lang.String methodName

values

java.util.Stack values

currentValue

XmlRpc.Value currentValue

cdata

java.lang.StringBuffer cdata

Used to collect character data (CDATA) of parameter values.

readCdata

boolean readCdata

STRING

static final int STRING

See Also:

Constant Field Values

INTEGER

static final int INTEGER

See Also:

Constant Field Values

BOOLEAN

static final int BOOLEAN

See Also:

Constant Field Values

DOUBLE

static final int DOUBLE

See Also:

Constant Field Values

DATE

static final int DATE

See Also:

Constant Field Values

BASE64

static final int BASE64

See Also:

Constant Field Values

STRUCT

static final int STRUCT

See Also:

Constant Field Values

ARRAY

static final int ARRAY

See Also:

Constant Field Values

errorLevel

int errorLevel

errorMsg

java.lang.String errorMsg

NONE

static final int NONE

See Also:

Constant Field Values

RECOVERABLE

static final int RECOVERABLE

See Also:

Constant Field Values

FATAL

static final int FATAL

See Also:

Constant Field Values

keepalive

static boolean keepalive

Wheter to use HTTP Keep-Alive headers.

debug

public static boolean debug

Whether to log debugging output.

types

static final java.lang.String[] types

The list of valid XML elements used for RPC.

encoding

static java.lang.String encoding

Java's name for the encoding we're using. Defaults to UTF8 (of which ISO8859_1 is a subset).

defaultInputEncoding

static java.lang.String defaultInputEncoding

Java's name for the input encoding we're using. Defaults to null, signifying the platform default. This may need to be overridden on platforms where the default encoding is not compatible with ASCII (eg. EBCDIC) but the network is still ASCII-like.

tz

java.util.TimeZone tz

Constructor Detail

XmlRpc

protected XmlRpc()

Creates a new instance with the TypeFactory set to an instance of the class named by the org.apache.xmlrpc.TypeFactory System property. If property not set or class is unavailable, uses the default of TypeFactory.

XmlRpc

protected XmlRpc(java.lang.String typeFactoryName)

Creates a new instance with the specified TypeFactory.

Parameters:

typeFactoryName - The fully qualified class name of the TypeFactory implementation to use.

Method Detail

setServerTimeZone

void setServerTimeZone(java.util.TimeZone z)

getServerTimeZone

java.util.TimeZone getServerTimeZone()

setDriver

public static void setDriver(java.lang.String driver)
                      throws java.lang.ClassNotFoundException

Set the SAX Parser to be used. The argument can either be the full class name or a user friendly shortcut if the parser is known to this class. The parsers that can currently be set by shortcut are listed in the main documentation page. If you are using another parser please send me the name of the SAX driver and I'll include it in a future release. If setDriver() is never called then the System property "sax.driver" is consulted. If that is not defined the driver defaults to OpenXML.

Throws:

java.lang.ClassNotFoundException

setDriver

public static void setDriver(java.lang.Class driver)

Set the SAX Parser to be used by directly passing the Class object.

setEncoding

public static void setEncoding(java.lang.String enc)

Set the encoding of the XML.

Parameters:

enc - The Java name of the encoding.

getEncoding

public java.lang.String getEncoding()

Return the encoding, transforming to the canonical name if possible.

See Also:

XmlWriter.canonicalizeEncoding(String)

setDefaultInputEncoding

public static void setDefaultInputEncoding(java.lang.String enc)

Set the default input encoding of the XML. This is used only if set.

Parameters:

enc - The Java name of the encoding.

See Also:

setInputEncoding(String)

getDefaultInputEncoding

public static java.lang.String getDefaultInputEncoding()

Return the default input encoding. This may be null. This is always a Java encoding name, it is not transformed.

Returns:

the Java encoding name to use, if set, otherwise null.

See Also:

getInputEncoding()

setInputEncoding

public void setInputEncoding(java.lang.String enc)

Set the input encoding for this XmlRpc instance. This can be used when the XMLRPC response does not contain the proper encoding information in the XML declaration.

Parameters:

enc - The Java name of the encoding.

getInputEncoding

public java.lang.String getInputEncoding()

Get the input encoding for this XmlRpc instance. This is a Java encoding name.

Returns:

The Java encoding name to use. null if not set.

getMaxThreads

public static int getMaxThreads()

Gets the maximum number of threads used at any given moment.

setMaxThreads

public static void setMaxThreads(int maxThreads)

Sets the maximum number of threads used at any given moment.

setDebug

public static void setDebug(boolean val)

Switch debugging output on/off.

setKeepAlive

public static void setKeepAlive(boolean val)

Switch HTTP keepalive on/off.

getKeepAlive

public static boolean getKeepAlive()

get current HTTP keepalive mode.

parse

void parse(java.io.InputStream is)
     throws java.lang.Exception

Parse the input stream. For each root level object, method objectParsed is called.

Throws:

java.lang.Exception

objectParsed

protected abstract void objectParsed(java.lang.Object what)

This method is called when a root level object has been parsed. Sub-classes implement this callback to receive the fully parsed object.

characters

public void characters(char[] ch,
                       int start,
                       int length)
                throws SAXException

Method called by SAX driver.

Specified by:

characters in interface DocumentHandler

Overrides:

characters in class HandlerBase

Parameters:

ch - The characters.

start - The start position in the character array.

length - The number of characters to use from the character array.

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

DocumentHandler.characters(char[], int, int)

endElement

public void endElement(java.lang.String name)
                throws SAXException

Method called by SAX driver.

Specified by:

endElement in interface DocumentHandler

Overrides:

endElement in class HandlerBase

Parameters:

name - The element type name.

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

DocumentHandler.endElement(java.lang.String)

startElement

public void startElement(java.lang.String name,
                         AttributeList atts)
                  throws SAXException

Method called by SAX driver.

Specified by:

startElement in interface DocumentHandler

Overrides:

startElement in class HandlerBase

Parameters:

name - The element type name.

atts - The specified or defaulted attributes.

Throws:

SAXException - Any SAX exception, possibly wrapping another exception.

See Also:

DocumentHandler.startElement(java.lang.String, org.xml.sax.AttributeList)

error

public void error(SAXParseException e)
           throws SAXException

Description copied from class: HandlerBase

Receive notification of a recoverable parser error.

The default implementation does nothing. Application writers may override this method in a subclass to take specific actions for each error, such as inserting the message in a log file or printing it to the console.

Specified by:

error in interface ErrorHandler

Overrides:

error in class HandlerBase

Parameters:

e -

Throws:

SAXException

See Also:

ErrorHandler.warning(org.xml.sax.SAXParseException), SAXParseException

fatalError

public void fatalError(SAXParseException e)
                throws SAXException

Description copied from class: HandlerBase

Report a fatal XML parsing error.

The default implementation throws a SAXParseException. Application writers may override this method in a subclass if they need to take specific actions for each fatal error (such as collecting all of the errors into a single report): in any case, the application must stop all regular processing when this method is invoked, since the document is no longer reliable, and the parser may no longer report parsing events.

Specified by:

fatalError in interface ErrorHandler

Overrides:

fatalError in class HandlerBase

Parameters:

e -

Throws:

SAXException

See Also:

ErrorHandler.fatalError(org.xml.sax.SAXParseException), SAXParseException