GWSService class documentation

Authors

Richard Frith-Macdonald (rfm@gnu.org)

Date: Generated at 2024-11-17 22:25:37 -0700

Copyright: (C) 2008 Free Software Foundation, Inc.


Contents -

  1. Software documentation for the GWSService class
  2. Software documentation for the GWSService(Delegate) category

Software documentation for the GWSService class

GWSService : NSObject

Declared in:
GWSService.h

The GWSService class provides methods for makeing a Remote Procedure Call (RPC) as a web services client.
Instances of this class are (in an ideal world) created and owned by instances the GWSDocument class as it parses a WSDL document, and contain information parsed from that document allowing them to set up the coding mechanism and URL to talk to.
However, standalone instances may be created to allow you to perform RPCs to a web services server when you dont have a fully specified WSDL document (or if the GWSDocument mechanism isn't working).

The class provides a method for making a synchronous RPC (with timeout), or an asynchronous RPC in which the call completion is handled by a delegate.

In order to simply make a synchronous call to a server, all you need to do is write code like:

   GWSService	*server;
   NSDictionary       *result;
   server = [GWSService new];
   [server setURL: @"http://server/path"];
   [server setCoder: [GWSSOAPCoder coder]];
   result = [server invokeMethod: name
                      parameters: p
                           order: o
                         timeout: 30];
 

Saying that you want to call the specified method ('name') on the server, passing the parameters ('p') in the order they are listed in 'o' and with a 30 second timeout.
If there is a network or http-level error or a timeout, the result will contain GWSErrorKey , otherwise it will contain GWSParametersKey , and GWSOrderKey on success, or GWSFaultKey if the remote end returns a fault.

Method summary

description 

+ (NSString*) description;
Returns a description of the current asynchronous service queues.

flushConnections: 

+ (void) flushConnections: (NSURL*)url;
Empty the cache of connections being kept alive to the specified URL or, if url is nil empty the entire cache.

setPerHostPool: 

+ (void) setPerHostPool: (unsigned)max;
Sets maximum active requests to a single host. This is silently limited to be no more than the value set by the +setPool: method.

setPerHostQMax: 

+ (void) setPerHostQMax: (unsigned)max;
Sets maximum queued requests to any single host.
This may be overridden for an individual host by using the +setReserve:forHost: method.

setPool: 

+ (void) setPool: (unsigned)max;
Sets the maximum number of simultaneous active async requests.
This is silently limited to the number of reserved hosts plus one on any attempt to set a lower value.

setQMax: 

+ (void) setQMax: (unsigned)max;
Sets the maximum number of queued async requests.
This may be overridden for an individual host by using the +setReserve:forHost: method.

setReserve: forHost: 

+ (void) setReserve: (unsigned)reserve forHost: (NSString*)host;
Sets a minimum queue size for a specific host... if the queue for this host is not full, an RPC can be queued even if the normal queue limits have been reached.
Setting a non-zero value for a host also reserves a single space in the connection pool for this host, so it is always possible for at least one request to be in progress to the host.
This setting overrides the values defined by the +setPerHostQMax: and +setQMax: methods.

setUseIOThreads: 

+ (void) setUseIOThreads: (BOOL)aFlag;
Sets whether the I/O for requests is to be performed in separate threads rather than the thread which queued the RPC.
Setting this option causes a small group of threads to be created and used to handle the I/O to the remote host.
If no work threads (see +setWorkThreads:) are enabled, the parsing of the response to the request is performed in the same thread that performed the I/O.
In any case, the -completedRPC: callback is sent to the thread which originally queued the RPC.

setWorkThreads: 

+ (void) setWorkThreads: (NSUInteger)count;
Sets the number of threads to be used for the building of request data to be POSTed to the remote system, the parsing of data received in response to that POST, and the callbacks to the delegate involved up to but excluding the execution of the -completedRPC: callback.
By default this is zero... so request data is built, and response data is parsed, in the thread which queues the request.

buildRequest: parameters: order: 

- (NSData*) buildRequest: (NSString*)method parameters: (NSDictionary*)parameters order: (NSArray*)order;
Builds an RPC method call.
The method argument is the name of the operation to be performed, however, if the receiver is owned by a GWSDocument instance which defines multiple ports for the service, the operation name may not be unique, in which case it must be specified as the port type and operation names separated by a full stop (port.operation).
Parameters must be supplied as for the [GWSCoder -buildRequest:parameters:order:] method.

coder 

- (GWSCoder*) coder;
Returns the coder instance used to serialize/deserialize for this instance.

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.

delegate 

- (id) delegate;
Returns the delegate previously set by the -setDelegate: method.
The delegate handles completion of asynchronous method calls to the URL specified when the receiver was initialised (if any).

documentation 

- (GWSElement*) documentation;
Return the documentation for the receiver.

getBytes: ofLength: byHandle: 

- (BOOL) getBytes: (const uint8_t*)bytes ofLength: (NSUInteger)length byHandle: (NSObject*)anObject;
Method called (if GNUstep debug logging is turned on) when a chunk of data from the HTTP request has been written. The default implementation returns NO (so default logging is used) unless the delegate supports the method (in which case the delegate method is used), but subclasses may override it to provide their own logging and return YES. When the delegate method is called, the handle sent to it is the GWSService instance.

headers 

- (NSDictionary*) headers;
Returns the value set by a previous call to the -setHeaders: method.

invokeMethod: parameters: order: timeout: 

- (NSMutableDictionary*) invokeMethod: (NSString*)method parameters: (NSDictionary*)parameters order: (NSArray*)order timeout: (int)seconds;
Calls -sendRequest:parameters:order:timeout:prioritised: and waits for the response.
Parameters must be supplied as for the [GWSCoder -buildRequest:parameters:order:] method.
Returns the response dictionary containing values for the success or failure of the call (as returned by -result).
Returns nil if it was impossible to build a valid request from the supplied parameters.

name 

- (NSString*) name;
Returns the name of this WSDL service.

objectForKey: 

- (id) objectForKey: (NSString*)aKey;
Returns the extra information (if any) associated with aKey by an earlier call to the -setObject:forKey: method.

putBytes: ofLength: byHandle: 

- (BOOL) putBytes: (const uint8_t*)bytes ofLength: (NSUInteger)length byHandle: (NSObject*)anObject;
Method called (if GNUstep debug logging is turned on) when a chunk of data from the HTTP request has been written. The default implementation returns NO (so default logging is used) unless the delegate supports the method (in which case the delegate method is used), but subclasses may override it to provide their own logging and return YES. When the delegate method is called, the handle sent to it is the GWSService instance.

result 

- (NSMutableDictionary*) result;
Returns the result of the last method call, or nil if there has been no method call or one is in progress.
The result is as produced by the [GWSCoder -parseMessage:] method.
NB. Any containers (arrays or dictionaries) in the parsed parameters of a success response will be mutable, so you can modify this data structure as you like.

sendRequest: parameters: order: timeout: 

- (BOOL) sendRequest: (NSString*)method parameters: (NSDictionary*)parameters order: (NSArray*)order timeout: (int)seconds;
Calls -sendRequest:parameters:order:timeout:prioritised: for a normal (non urgent) request.

sendRequest: parameters: order: timeout: prioritised: 

- (BOOL) sendRequest: (NSString*)method parameters: (NSDictionary*)parameters order: (NSArray*)order timeout: (int)seconds prioritised: (BOOL)urgent;
Send an asynchronous RPC method call with the specified timeout.
The method argument is the name of the operation to be performed, however, if the receiver is owned by a GWSDocument instance which defines multiple ports for the service, the operation name may not be unique, in which case it must be specified as the port type and operation names separated by a full stop (port.operation).
A delegate should have been set to handle the result of this call, but if one was not set the state of the asynchronous call may be polled by calling the -result method, which will return nil as long as the call has not completed.
The call may be cancelled by calling the -timeout: method.
This method returns YES if the call was started, NO if it could not be started (eg because there is already a call in progress for the receiver, or too many other calls are in progress in total, or because of bad arguments).
NB. For the asynchronous operation to proceed, the current NSRunLoop must be run.
Parameters must be supplied as for the [GWSCoder -buildRequest:parameters:order:] method.

setCoder: 

- (void) setCoder: (GWSCoder*)aCoder;
Sets the coder to be used by the receiver for encoding to XML and decoding from XML. If this is not called, the receiver creates a coder as needed.
Calling this method sets the receiver as the delegate of the coder, or raises an NSInvalidArgumentException if the coder already had a different delegate.

setContentType: 

- (void) setContentType: (NSString*)cType;
Sets the value of the Content-Type header to be sent with a request.
Setting a nil or empty string value reverts to the default of text/xml.

setDebug: 

- (int) setDebug: (int)flag;
Specifies whether debug information is enabled. See -debug for more information.
A non-zero setting sets debug to YES while a zero setting sets it to NO. The method returns the previous setting.

setDelegate: 

- (void) setDelegate: (id)aDelegate;
Sets the delegate object which will receive callbacks when an RPC call completes.
NB. this delegate is not retained, and should be removed before it is deallocated (call -setDelegate: again with a nil argument to remove the delegate).

setDocumentation: 

- (void) setDocumentation: (GWSElement*)documentation;
Set the documentation for the receiver.

setHTTPMethod: 

- (void) setHTTPMethod: (NSString*)method;
Sets the value of the HTTP method to be used for a request.
Setting an nil string reverts to the default 'POST' method.

setHeaders: 

- (void) setHeaders: (NSDictionary*)headers;
Sets extra headers to be sent as part of any HTTP or HTTPS request initiated by this service.
NB. These headers are set *after* the default headers set for content type and user agent etc, so you can override the values normally set by the service.

setNewAPI: 

- (BOOL) setNewAPI: (BOOL)aFlag;
Controls whether the new (NSURLConnection/NSURLRequest) API is used or the old (NSURLHandle) API is used. The default depends on the platform (GNUstep uses the old API while Apple uses the new).
Turning on debug or the use of client certificates overrides this to use the old API since the new one does not yet support those features.

setObject: forKey: 

- (void) setObject: (id)anObject forKey: (NSString*)aKey;
Tags the service with entra information in the form of anObject references by aKey. if anObject is nil, this removes any previous association for aKey.
This facility is not used by the WebServices library, and is present purely so that delegates can associate extra information with the services they are handling.

setSOAPAction: 

- (void) setSOAPAction: (NSString*)action;
Sets the value of the SOAPAction header to be sent with a request.
Setting an nil string value suppresses the sending of this header.
Most servers expect two double quotes characters for this, so you should probably set @"\"\"" as the action.

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.

setURL: 

- (void) setURL: (id)url;
Sets up the receiver to make XMLRPC calls to the specified URL.
This method just calls -initWithURL:certificate:privateKey:password: with nil arguments for the SSL credentials.

setURL: certificate: privateKey: password: 

- (void) setURL: (id)url certificate: (NSString*)cert privateKey: (NSString*)pKey password: (NSString*)pwd;
Sets up the receiver to make XMLRPC calls to the specified url and (optionally) with the specified SSL parameters.
The url argument may be nil, in which case the receiver will be unable to make XMLRPC calls, but can be used to parse incoming requests and build responses.
The url can actually be either a string or an instance of NSURL.
If the SSL credentials are non-nil, connections to the remote server will be authenticated using the supplied certificate so that the remote system knows who is contacting it.
Certificate based authentication currently NOT implemented * for MacOS-X (though it is for GNUstep).
Please could someone let me know how certificate based authentication is done for HTTPS on MacOS-X?

timeZone 

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

timeout: 

- (void) timeout: (NSTimer*)t;
Handles timeouts, passing information to delegate ... you don't need to call this method, but you may call it (with nil as its argument) in order to cancel an asynchronous request as if it had timed out.

tree 

- (GWSElement*) tree;
Return a tree representation of the receiver for output as part of a WSDL document.

webServiceOperation 

- (NSString*) webServiceOperation;
Returns the name of the current operation being performed, or nil if there is no operation in progress.
In conjunction with -webServicePort this method can be used to look up all the details of the WSDL definition of the operation being performed.

webServiceParameters 

- (NSMutableDictionary*) webServiceParameters;
Returns the parameter dictionary of the current operation being performed, or nil if there is no operation in progress.
This method can be used to determine exactly what data is being passed in the current operation.

webServicePort 

- (GWSPort*) webServicePort;
Returns the port of the current operation being performed, or nil if there is no operation in progress.
In conjunction with -webServiceOperation this method can be used to look up all the details of the WSDL definition of the operation being performed.

Software documentation for the GWSService(Delegate) category

GWSService(Delegate)

Declared in:
GWSService.h
Delegates should implement this method in order to be informed of the success or failure of an XMLRPC method call which was initiated by the -sendRequest:parameters:order:timeout: method.
Method summary

completedRPC: 

- (void) completedRPC: (GWSService*)sender;
An empty method provided for subclasses to override.
Called by the sender when an RPC method call completes (either success or failure). The delegate may then call the -result method to retrieve the result of the method call from the sender.

webService: buildRequest: parameters: order: 

- (NSData*) webService: (GWSService*)service buildRequest: (NSString*)method parameters: (NSDictionary*)parameters order: (NSArray*)order;
This method informs the delegate that the service is about to configure itsself to build the request data for a request (by calling the -buildRequest:parameters:order: method). If the delegate method returns an NSData object, the request will not be built and the returned object will be used instead. If the delegate method returns nil, the normal request build will go ahead.

webService: didEncode: 

- (GWSElement*) webService: (GWSService*)service didEncode: (GWSElement*)element;
This method is used to inform the delegate of the encoded XML request (a GWSElement instance) which will be sent to the remote system.
The delegate may modify or replace this and must return the replacement value or the modified element tree.

webService: handleResponse: 

- (NSMutableDictionary*) webService: (GWSService*)service handleResponse: (NSData*)response;
This method informs the delegate that the service is about to parse response data from the remote system and place the results in a mutable dictionary.
If the delegate method returns nil, the response data will be processed as normal, otherwise the delegate is reponsible for the parsing of the data and production of the results dictionary.

webService: willDecode: 

- (GWSElement*) webService: (GWSService*)service 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.

webService: willEncode: 

- (GWSElement*) webService: (GWSService*)service 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.

webService: willHandleResponse: 

- (NSData*) webService: (GWSService*)sender willHandleResponse: (NSData*)data;
An empty method provided for subclasses to override.
Called by the sender when it is about to handle response data from a remote server. The delegate may return a different data item to be decoded and/or take this opportunity to change the service settings before the response is handled.

webService: willSendRequest: 

- (NSData*) webService: (GWSService*)sender willSendRequest: (NSData*)data;
An empty method provided for subclasses to override.
Called by the sender when it is about to send an encoded request to a remote server. The delegate may return a different data item to be sent and/or take this opportunity to change the service settings (such as the URL to send to) before the data is actualy sent.