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:
- 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
+ (NSString*)
description;
Returns a description of the current asynchronous
service queues.
+ (void)
setPerHostPool: (unsigned)max;
Sets maximum connections to a single host.
+ (void)
setPool: (unsigned)max;
Sets the maximum number of simultaneous async
connections.
- (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.
- (
GWSCoder*)
coder;
Returns the coder instance used to
serialize/deserialize for this
instance.
- (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.
- (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).
- (
GWSElement*)
documentation;
Return the documentation for the receiver.
- (NSDictionary*)
headers;
Returns the value set by a previous call to the
-setHeaders:
method.
- (NSMutableDictionary*)
invokeMethod: (NSString*)method
parameters: (NSDictionary*)parameters
order: (NSArray*)order
timeout: (int)seconds;
- (NSString*)
name;
Returns the name of this WSDL service.
- (id)
objectForKey: (NSString*)aKey;
Returns the extra information (if any) associated
with
aKey by an earlier call to the
-setObject:forKey:
method.
- (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.
- (BOOL)
sendRequest: (NSString*)method
parameters: (NSDictionary*)parameters
order: (NSArray*)order
timeout: (int)seconds;
- (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 another call is in progress 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.
- (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.
- (void)
setDebug: (BOOL)flag;
Specifies whether debug information is enabled.
See
-debug
for
more information.
- (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).
- (void)
setDocumentation: (
GWSElement*)documentation;
Set the documentation for the receiver.
- (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 yu can override the values normally
set by the service.
- (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.
- (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.
- (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.
- (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.
- (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?
- (NSTimeZone*)
timeZone;
Return the time zone currently set.
- (void)
timeout: (NSTimer*)t;
Handles timeouts, passing information to delegate
... you don't need to call this method, but you
may call it in order to cancel an
asynchronous request as if it had timed out.
- (
GWSElement*)
tree;
Return a tree representation of the receiver for
output as part of a WSDL document.
- (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.
- (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.
- (
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.
- Declared in:
- GWSService.h
Method summary
- (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.
- (
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.
- (
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.
- (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.
- (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.