Authors
- Richard Frith-Macdonald (
rfm@gnu.org
)
-
Version: 25485
Date: 2007-09-14 13:54:55 +0100 (Fri, 14 Sep 2007)
Copyright: (C) 2008 Free Software Foundation, Inc.
- Declared in:
- GWSCoder.h
The GWSCoder class is a semi-abstract class for
handling encoding to XML and decoding from XML for
a group of services.
With its standard instance
variables and helper functions it really just
provides a convenient mechanism to store data in a
mutable string, but in conjunction with
GWSElement
it can be used to serialize a tree of elements to a
string and will parse an XML document ninto a tree
of elements.
Usually (for RPC and messaging),
the actual encoding/decoding is handled by a concrete
subclass.
Instances of these classes are
not expected to be re-entrant or thread-safe, so you
need to create an instance for each thread in which
you are working.
With Web Services, the design of the XML
specification is that services have an
abstract definition and then also a concrete
binding to a particular implementation (generally
SOAP).
Within the GWS classes a similar
separation is implemented at the level of the
coders, with the idea being that coders can be
used separately and their operation can be driven
entirely from the parameter dictionary passed to
them (with various special keys in the dictionary
controlling behavior).
Thus to send a
message for a particular service, the basic
parameters are placed in a dictionary by the
application, and that dictionary is then
passed to the GWSService which invokes
extensibility classes to modify the
dictionary contents by adding additional
keys/values to tell the coder how to handle
them.
A programmer wishing to use the coder
without web services support to, simply send an
RPC, merely needs to supply any required additional
key/value pairs themselves rather than having a
web service do it.
Instance Variables
Method summary
+ (
GWSCoder*)
coder;
Creates and returns an autoreleased instance.
The default implementation creates an
instance of the GWSXMLRPCCoder concrete subclass.
- (BOOL)
compact;
Return the value set by a prior call to
-setCompact:
(or
NO
... the default).
- (BOOL)
debug;
Returns
YES
if debug is enabled,
NO
otherwise. The default value of this
is obtained from the GWSDebug user default (or
NO
if no default is set), but may also
be adjusted by a call to the
-setDebug:
method.
- (NSData*)
decodeBase64From: (NSString*)str;
Decode the supplied base64 encoded data and return
the result.
- (NSData*)
decodeHexBinaryFrom: (NSString*)str;
Decode the supplied hexBinary encoded data and
return the result.
This is a tolerant parser,
it accepts lower case hex digits and white space, but it
does insist on an even number of hexadecimal digits.
A decoding failure results in
nil
being returned.
- (NSString*)
encodeBase64From: (NSData*)source;
Take the supplied data and convert it to base64
encoded text.
- (NSString*)
encodeHexBinaryFrom: (NSData*)source;
Encode the supplied data as hexBinary data in the
canonical form (as per W3 schema recommendations)
and return the result.
The canonical form uses
upper case hexadecimal digits.
- (NSString*)
escapeXMLFrom: (NSString*)str;
Take the supplied string and add all necessary escapes
for XML.
- (void)
indent;
Increase the indentation level used while creating
an XML document.
- (NSMutableString*)
mutableString;
Returns the mutable string currently in use for
encoding.
- (void)
nl;
Add a new line to the temporary string currently in use
for creating an XML document, and add padding on the
new line so that the next item written is indented
correctly.
- (
GWSElement*)
parseXML: (NSData*)xml;
Parses XML data to form a tree of GWSElement
objects.
This method uses the
NSXMLParser
class to perform the actual parsing by acting as a
delegate to build a tree of
GWSElement
objects, so you may use your own subclass and
override the NSXMLParser delegate methods to
provide additional control over the parsing
operation.
- (id)
parseXSI: (NSString*)type
string: (NSString*)value;
Parses simple XSI typed string data into Objective-C
objects.
The type is the name of
the simple datatype (if nil
,
'xsd:string').
The value
is the string to be decoded.
The result returned
may be an NSString, and NSNumber, an NSDate or an
NSData object.
A result of nil
is returned if the value cannot be decoded as
the specified type.
- (void)
reset;
Resets parsing and/or building, releasing any
temporary data stored during parse etc.
- (void)
setCompact: (BOOL)flag;
Specify whether to generate compact XML (omit
indentation and other white space and omit
<string> element markup for XMLRPC).
Compact representation saves some space (can
be important when sent over slow/low bandwidth
connections), but sacrifices readability.
- (void)
setDebug: (BOOL)flag;
Specifies whether debug information is enabled.
See
-debug
for
more information.
- (void)
unindent;
Decrease the indentation level used while creating
an XML document. creating an XML document.
Instance Variables for GWSCoder Class
@protected NSMutableArray* _stack;
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
- Declared in:
- GWSCoder.h
The GWSSOAPCCoder class is a concrete subclass of
GWSCoder
which implements coding/decoding for the SOAP
protocol.
Dictionaries passed to/from the SOAP coder
may contain special keys with the
GWSSOAP
prefix which control the
coding rather than specifying values to be coded
(this is in addition to the special
GWSOrderKey
used for ordering fields in a complex type).
See the section on constants for a description of
what the keys below are used for:
Instance Variables
Method summary
- (NSString*)
encodeDateTimeFrom: (NSDate*)source;
Take the supplied data and return it in the format
used for an xsd:dateTime typed element.
This
uses the timezone currently set in the receiver to
determine the time of day encoded and to provide
the timezone offset in the encoded string.
- (NSString*)
operationStyle;
- (void)
setOperationStyle: (NSString*)style;
- (void)
setUseLiteral: (BOOL)use;
Sets the encoding usage in operation to be 'literal' (
YES
) or encoded (NO
).
- (BOOL)
useLiteral;
Returns whether the encoding usage in operation is
'literal' (YES
) or 'encoded' (
NO
).
Instance Variables for GWSSOAPCoder Class
@protected NSString* _style;
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
@protected BOOL _useLiteral;
Warning the underscore at the start of the
name of this instance variable indicates that, even
though it is not technically private, it is
intended for internal use within the package, and
you should not use the variable in other code.
- Declared in:
- GWSCoder.h
The GWSXMLRPCCoder class is a concrete subclass of
GWSCoder
which implements coding/decoding for the XMLRPC
protocol.
The correspondence between XMLRPC values and
Objective-C objects is as follows -
-
i4 (or
int) is an
NSNumber
other than a real/float or boolean.
-
boolean is an
NSNumber
created as a BOOL.
-
string is an
NSString
object.
-
double is an
NSNumber
created as a float or
double.
-
dateTime.iso8601 is
an
NSDate
object.
-
base64 is an
NSData
object.
-
array is an
NSArray
object.
-
struct is an NSDictionary
object.
If you attempt to use any other type of object in the construction of an XMLRPC document, the [NSObject -description]
method of that object will be used to create a string, and the resulting object will be encoded as an XMLRPC string element.
In particular, the names of members in
a struct must be strings, so
if you provide an
NSDictionary
object to represent a struct the keys of the dictionary will be converted to strings where necessary.
Method summary
- (NSString*)
encodeDateTimeFrom: (NSDate*)source;
Take the supplied data and encode it as an XMLRPC
timestamp.
This uses the timezone
currently set in the receiver to determine the
time of day encoded.
- Declared in:
- GWSCoder.h
The methods in this category are used to handle web
services RPC and messaging tasks. Most of these
methods are implemented by subclasses and cannmot be
used in the base class.
Method summary
- (NSData*)
buildFaultWithParameters: (NSDictionary*)parameters
order: (NSArray*)order;
Constructs an XML document for an RPC fault
response with the specified
parameters.
The resulting document is returned as an NSData object.
For XMLRCP the two
parameters
should be faultCode (an integer) and faultString.
The
order array may be empty or
nil
if the
order of the
parameters is not important, otherwise it
must contain the names of the
parameters in
the
order in which they are to be encoded.
This method simply calls
-setFault:
to say that a fault is being built, then calls
-buildRequest:parameters:order:
with a
nil
request name, and calls
-setFault:
again before returning the result. If you override
this method in a subclass, you should perform the same
handling of the fault flag.
This method is
intended for use by applications acting as RPC
servers.
- (NSData*)
buildRequest: (NSString*)method
parameters: (NSDictionary*)parameters
order: (NSArray*)order;
Subclasses
must override this method.
Given a method name and a set of
parameters, this method
constructs the XML document for the
corresponding message or RPC call and returns
the document as an NSData object.
The
parameters dictionary may be empty or
nil
if there are no
parameters to be passed.
The
order array may be empty or
nil
if the order of the
parameters is not important, otherwise it
must contain the names of the parameters in
the order in which they are to be encoded.
If composite data types within the
parameters dictionary contain fields which
must be sent in a specific order, the
dictionary containing those fields may contain a
key 'GWSOrderKey' whose value is an array containing
the names of those fields in the order of
their encoding.
The method returns
nil
if passed an invalid
method name.
This method
is used internally when sending an RPC method
call to a remote system, but you can also call it
yourself.
- (NSData*)
buildResponse: (NSString*)method
parameters: (NSDictionary*)parameters
order: (NSArray*)order;
Subclasses
must override this method.
Builds an RPC response with the specified set of
parameters and returns the document as an
NSData object.
The method name may
be nil
(and is indeed ignored for XMLRPC)
where any parameters are not wrapped
inside a method.
The
parameters dictionary may be empty or
nil
if there are no
parameters to be returned (an empty
parameters element will be created).
The order array may be empty or
nil
if the order of the
parameters is not important, otherwise it
must contain the names of the parameters in
the order in which they are to be encoded.
This method is intended for use by
applications acting as RPC servers.
- (id)
delegate;
Returns the RPC encoding delegate (if any) set by a
previous call to the
-setDelegate:
method.
Normally the delegate of a coder is
the GWSService instance which owns it... a service will
automatically set itsself as the coder's
delegate when the coder is set in the service, so
if you need to have a different delegate, you should set
it after adding the coder to the service.
- (BOOL)
fault;
Returns a flag to say whether this coder is
encoding/decoding a fault or not.
- (NSMutableDictionary*)
parseMessage: (NSData*)data;
Subclasses
must override this method.
Parses
data containing an method call or
message etc.
The result dictionary may
contain
GWSMethodKey
,
GWSParametersKey
, and
GWSOrderKey
on success, or
GWSErrorKey
on failure.
NB. Any containers (arrays or
dictionaries) in the parsed parameters will
be mutable, so you can modify this
data
structure as you like.
This method is
intended for the use of server applications.
- (void)
setDelegate: (id)delegate;
Sets a delegate to handle decoding and
encoding of data items.
The
delegate should implement the informal
GWSCoder protocol to either handle the
encoding/decoding or to inform the coder
that it won't do it for a particular case.
- (void)
setFault: (BOOL)flag;
Sets the fault flag to indicate that a
fault is being encoded or decoded.
- (void)
setTimeZone: (NSTimeZone*)timeZone;
Sets the time zone for use when sending/receiving
date/time values.
The XMLRPC specification
says that timezone is server dependent so you will
need to set it according to the server you are
connecting to.
If this is not set, UCT is
assumed.
- (NSTimeZone*)
timeZone;
Return the time zone currently set.
- Declared in:
- GWSCoder.h
This informal protocol specifies the methods that a
coder delegate may implement in order to override
general encoding/decoding of service arguments.
Generally the delegate is a
GWSService
instance.
Method summary
- (id)
decodeWithCoder: (
GWSCoder*)coder
item: (
GWSElement*)item
named: (NSString*)name;
This method is called to ask the delegate to decode
the specified element and return the result. If the
delegate does not wish to decode the element, it
should simply return nil
.
The
name and ctxt arguments provide context
for decoding, allowing the delegate to better
understand how the element should be decoded...
the ctxt is the parent element of the item
being decoded, and the name is the
identifier that will be used for the
item.
The default implementation
returns nil
.
- (BOOL)
encodeWithCoder: (
GWSCoder*)coder
item: (id)item
named: (NSString*)name
in: (
GWSElement*)ctxt;
This method is called to ask the delegate to encode
the specified item with the given
name into the parent context.
The
delegate must return NO
if it does
not wish to encode the item itsself,
otherwise it must return YES
after
adding the new element as a child of ctxt
.
The name is the key used to identify
the item in in its current context (normally
the name of the element it will be encoded
to).
The default implementation returns
NO
.
- (NSString*)
webServiceOperation;
Returns the name of the operation that the receiver
is being used to implement.
- (
GWSPort*)
webServicePort;
Returns the port object defining the binding and
address of the operation being performed.
- Declared in:
- GWSCoder.h
This informal protocol specifies the methods that a
coder delegate may implement in order to modify or
overriding encoding/decoding of SOAP specific
message components.
Method summary
- (
GWSElement*)
coder: (
GWSSOAPCoder*)coder
willDecode: (
GWSElement*)element;
This method is used to inform the delegate of the
GWSElement instance being decoded as the SOAP
Envelope, Header, Body, Fault or Method.
The instance to be decoded will contain the children
from the document being decoded.
The delegate
implementation should return the proposed
instance (possibly modified) or a different object
that it wishes the coder to use.
The
default implementation returns element.
- (
GWSElement*)
coder: (
GWSSOAPCoder*)coder
willEncode: (
GWSElement*)element;
This method is used to inform the delegate of the
proposed
GWSElement
instance used to encode SOAP Envelope, Header,
Body, Fault or Method elements.
The proposed
instance will not have any children at the point
where this method is called (they are added later
in the encoding process.
This method may be
called with a
nil
value for the
element parameter in the case where no
Header
element would be encoded... in
this situation the delegate may return a Header
element to be used, or may return some
other
element, which will be
automatically inserted into a standard
header.
The delegate implementation should
return the proposed instance (possibly modified)
or a different object that it wishes the
coder to encode instead.
The
default implementation returns
element
.
NB. A Fault or Method will obviously only be
provided where the message contain such an
element, and the Header will only be
provided where the message has been told to
contain headers by use of the
GWSSOAPMessageHeadersKey
in the parameters dictionary.