Authors
- Richard Frith-Macdonald (
rfm@gnu.org
)
-
Date: Generated at 2024-11-17 22:25:37 -0700
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)
flushConnections: (NSURL*)url;
Empty the cache of connections being kept alive to
the specified URL or, if url is
nil
empty the entire cache.
+ (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.
+ (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.
+ (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.
+ (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.
+ (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.
+ (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.
+ (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.
- (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.
- (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.
- (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;
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.
- (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.
- (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.
- (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 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.
- (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)
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.
- (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.
- (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)
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.
- (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.
- (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.
- (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 (with nil
as its
argument) 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.
- (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.
- (
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.
- (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.
- (
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.