# GWSCoder documentation

### 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.

### Contents -

1. Software documentation for the GWSCoder class
2. Software documentation for the GWSJSONCoder class
3. Software documentation for the GWSSOAPCoder class
4. Software documentation for the GWSXMLRPCCoder class
5. Software documentation for the GWSCoder(RPC) category
6. Software documentation for the NSArray(JSON) category
7. Software documentation for the NSData(JSON) category
8. Software documentation for the NSDictionary(JSON) category
9. Software documentation for the NSObject(GWSCoder) category
10. Software documentation for the NSObject(GWSSOAPCoder) informal protocol
11. Software documentation for the NSString(JSON) category

# Software documentation for the GWSCoder class

## GWSCoder : NSObject

> 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

- -buildFaultWithParameters:order:
- -buildRequest:parameters:order:
- -buildResponse:parameters:order:
- -delegate
- -fault
- -parseMessage:
- -setDelegate:
- -setFault:
- -setTimeZone:
- -timeZone
- +coder
- -compact
- -debug
- -decodeBase64From:
- -decodeHexBinaryFrom:
- -encodeBase64From:
- -encodeHexBinaryFrom:
- -escapeXMLFrom:
- -indent
- -mutableString
- -nl
- -parseXML:
- -parseXSI:string:
- -reset
- -setCompact:
- -setDebug:
- -unindent

### coder

+ (GWSCoder*) coder;
Creates and returns an autoreleased instance.
The default implementation creates an instance of the GWSXMLRPCCoder concrete subclass.

### compact

- (BOOL) compact;
Return the value set by a prior call to -setCompact: (or `NO`... the default).

### debug

- (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.

### decodeBase64From:

- (NSData*) decodeBase64From: (NSString*)str;
Decode the supplied base64 encoded data and return the result.

### decodeHexBinaryFrom:

- (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.

### encodeBase64From:

- (NSString*) encodeBase64From: (NSData*)source;
Take the supplied data and convert it to base64 encoded text.

### encodeHexBinaryFrom:

- (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.

### escapeXMLFrom:

- (NSString*) escapeXMLFrom: (NSString*)str;
Take the supplied string and add all necessary escapes for XML.

### indent

- (void) indent;
Increase the indentation level used while creating an XML document.

### mutableString

- (NSMutableString*) mutableString;
Returns the mutable string currently in use for encoding.

### nl

- (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.

### parseXML:

- (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.

### parseXSI: string:

- (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.

### reset

- (void) reset;
Resets parsing and/or building, releasing any temporary data stored during parse etc.

### setCompact:

- (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.

### setDebug:

- (void) setDebug: (BOOL)flag;
Specifies whether debug information is enabled. See -debug for more information.

### unindent

- (void) unindent;
Decrease the indentation level used while creating an XML document. creating an XML document.

## Instance Variables for GWSCoder Class

### _stack

@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.

# Software documentation for the GWSJSONCoder class

## GWSJSONCoder : GWSCoder

> Declared in:
>   GWSCoder.h

The GWSJSONCoder class is a concrete subclass of GWSCoder which implements coding/decoding for JSON texts.

The correspondence between JSON values and Objective-C objects is as follows -

- null is the NSNull object.
- true is an NSNumber created as a BOOL.
- false is an NSNumber created as a BOOL.
- numeric is an NSNumber other than a boolean.
- string is an NSString object.
- array is an NSArray object.
- object is an NSDictionary object.

In addition, any NSDate object is encoded as a string using the -encodeDateTimeFrom: method, and any NSData object is encoded as a string by using base64 encoding.

If you attempt to use any other type of object in the construction of a JSON text, the [NSObject -description] method of that object will be used to create a string, and the resulting object will be encoded as a JSON string element.

In particular, the names of members in a JSON object must be strings, so if you provide an NSDictionary object to represent a JSON object the keys of the dictionary will be converted to strings where necessary.

Method summary

- -buildRequest:parameters:order:
- -buildResponse:parameters:order:
- -encodeDateTimeFrom:

### buildRequest: parameters: order:

- (NSData*) buildRequest: (NSString*)method parameters: (NSDictionary*)parameters order: (NSArray*)order;

The JSON text format does not include the notion of a remote procedure call and consists of a single array or a single JSON object.
To work with this rather crude behavior, the GWSJSONCoder class ignores the method argument and makes use of other arguments as follows:
If the order argument is non-null, it is interpreted as containing the names of values in the parameters dictionary which are to be sent as an array in the JSON text, any any values missing from the dictionary are sent as null objects in the array.
Otherwise, the contents of the parameters dictionary are sent as a JSON object. The special keys GWSOrderKey and GWSParametersKey are used as normal.

### buildResponse: parameters: order:

- (NSData*) buildResponse: (NSString*)method parameters: (NSDictionary*)parameters order: (NSArray*)order;
This method simply calls the =buildRequest:parameters:object: method.

### encodeDateTimeFrom:

- (NSString*) encodeDateTimeFrom: (NSDate*)source;
Take the supplied date and encode it as a string.
This uses the timezone currently set in the receiver to determine the time of day encoded.
There is no standard for JSON timestamps.

# Software documentation for the GWSSOAPCoder class

## GWSSOAPCoder : GWSCoder

> 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:

- GWSSOAPBodyEncodingStyleKey
- GWSSOAPMessageHeadersKey
- GWSSOAPNamespaceNameKey
- GWSSOAPNamespaceURIKey
- GWSSOAPUseKey

Instance Variables
Method summary

- -encodeDateTimeFrom:
- -operationStyle
- -setOperationStyle:
- -setUseLiteral:
- -useLiteral

### encodeDateTimeFrom:

- (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.

### operationStyle

- (NSString*) operationStyle;
Returns the style of message being used for encoding by the receiver. One of GWSSOAPBodyEncodingStyleDocument or GWSSOAPBodyEncodingStyleRPC or GWSSOAPBodyEncodingStyleWrapped

### setOperationStyle:

- (void) setOperationStyle: (NSString*)style;
Sets the style for this coder to be GWSSOAPBodyEncodingStyleDocument or GWSSOAPBodyEncodingStyleRPC or GWSSOAPBodyEncodingStyleWrapped

### setUseLiteral:

- (void) setUseLiteral: (BOOL)use;
Sets the encoding usage in operation to be 'literal' ( `YES`) or encoded (`NO`).

### useLiteral

- (BOOL) useLiteral;
Returns whether the encoding usage in operation is 'literal' (`YES`) or 'encoded' ( `NO`).

## Instance Variables for GWSSOAPCoder Class

### _style

@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.

### _useLiteral

@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.

# Software documentation for the GWSXMLRPCCoder class

## GWSXMLRPCCoder : GWSCoder

> 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

- -encodeDateTimeFrom:

### encodeDateTimeFrom:

- (NSString*) encodeDateTimeFrom: (NSDate*)source;
Take the supplied date and encode it as an XMLRPC timestamp.
This uses the timezone currently set in the receiver to determine the time of day encoded.

# Software documentation for the GWSCoder(RPC) category

## GWSCoder(RPC)

> 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

- -buildFaultWithParameters:order:
- -buildRequest:parameters:order:
- -buildResponse:parameters:order:
- -delegate
- -fault
- -parseMessage:
- -setDelegate:
- -setFault:
- -setTimeZone:
- -timeZone

### buildFaultWithParameters: order:

- (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.

### buildRequest: parameters: order:

- (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 document for the corresponding message or RPC call and returns it 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.
An array keyed on 'GWSOrderKey' in top level parameters dictionary overrides the order argument.
A dictionary keyed on 'GWSParametersKey' in top level parameters dictionary overrides the parameters argument (ie the content of the lower level dictionary is treated as the container of the actual parameters).
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.

### buildResponse: parameters: order:

- (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.

### delegate

- (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.

### fault

- (BOOL) fault;
Returns a flag to say whether this coder is encoding/decoding a fault or not.

### parseMessage:

- (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.

### setDelegate:

- (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.

### setFault:

- (void) setFault: (BOOL)flag;
Sets the fault flag to indicate that a fault is being encoded or decoded.

### setTimeZone:

- (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.

### timeZone

- (NSTimeZone*) timeZone;
Return the time zone currently set.

# Software documentation for the NSArray(JSON) category

## NSArray(JSON)

> Declared in:
>   GWSCoder.h

Description forthcoming.
Method summary

- -JSONText

### JSONText

- (NSData*) JSONText;
Return the receiver encoded as a JSON text in UTF-8 encoding.

# Software documentation for the NSData(JSON) category

## NSData(JSON)

> Declared in:
>   GWSCoder.h

Description forthcoming.
Method summary

- -JSONPropertyList

### JSONPropertyList

- (id) JSONPropertyList;
Parse the receiver as a JSON property list and return the result.

# Software documentation for the NSDictionary(JSON) category

## NSDictionary(JSON)

> Declared in:
>   GWSCoder.h

Description forthcoming.
Method summary

- -JSONText

### JSONText

- (NSData*) JSONText;
Return the receiver encoded as a JSON text in UTF-8 encoding.

# Software documentation for the NSObject(GWSCoder) category

## NSObject(GWSCoder)

> 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

- -decodeWithCoder:item:named:
- -encodeWithCoder:item:named:in:
- -webServiceOperation
- -webServicePort

### decodeWithCoder: item: named:

- (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`.

### encodeWithCoder: item: named: in:

- (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`.

### webServiceOperation

- (NSString*) webServiceOperation;
Returns the name of the operation that the receiver is being used to implement.

### webServicePort

- (GWSPort*) webServicePort;
Returns the port object defining the binding and address of the operation being performed.

# Software documentation for the NSObject(GWSSOAPCoder) informal protocol

## NSObject(GWSSOAPCoder)

> 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

- -coder:willDecode:
- -coder:willEncode:

### coder: willDecode:

- (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.

### coder: willEncode:

- (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.

# Software documentation for the NSString(JSON) category

## NSString(JSON)

> Declared in:
>   GWSCoder.h

Description forthcoming.
Method summary

- -JSONPropertyList

### JSONPropertyList

- (id) JSONPropertyList;
Parse the receiver as a JSON property list and return the result.