Class WOAdaptor

CLASS DESCRIPTION

Inherits From:
NSObject

WOAdaptor is an abstract class that represents objects that can receive events from a WebObjects adaptor. A WebObjects adaptor is a process that handles communication between the server and a WebObjects application. The WebObjects application (a WOApplication instance) communicates with the adaptor using messages defined in the WOAdaptor class.

WebObjects offers several choices of adaptors that you can use, all of which handle HTTP requests. You may want to write your own adaptor to handle other kinds of requests, such as DO, CORBA, or DCOM. If you write your own adaptor, you will also need to write your own WOAdaptor subclass.

The purpose of the WOAdaptor class is to perform these tasks:

All of the provided WebObjects adaptors use a subclass of WOAdaptor named WODefaultAdaptor to communicate with WOApplication. The source code for the WODefaultAdaptor implementation is distributed with WebObjects in the directory NeXT_ROOT/NextLibrary/WOAdaptors/CGI/Source/Application. Use this class as an example when creating your own WOAdaptor subclass.

Creating a New WOAdaptor Instance

You specify the adaptor(s) you want to use on the command line when you start a WebObjects application. If you autostart the application or if you do not specify the adaptor, the application uses the default HTTP adaptor (WODefaultAdaptor). To specify a custom subclass of WOAdaptor, use the -a option. For example, the following command starts up the DodgeDemo example using a subclass of WOAdaptor named MyHTTPSAdaptor.

DodgeDemo.exe -a MyHTTPSAdaptor

When the WOApplication object encounters the -a option, it sends itself an adaptorWithName:arguments: message. This method allocates the WOAdaptor subclass (MyHTTPSAdaptor in this example) and initializes it with the message initWithName:arguments:application:.

You can specify more than one adaptor per application if they are of different types. (For example, you could have a separate adaptor with its own port for communicating directly with Java applets on the browser.) If you specify multiple HTTP adaptors, only the last one specified will be used.

Adaptor-Specific Command Line Arguments

If you specify an adaptor on the application command line, you can pass arguments to the WOAdaptor class as well. You can pass any options defined by your subclass. The application passes all options following a -a option up until the next -a, -c, or -d option or the application name to the adaptor.

For a list of options you can specify for the WODefaultAdaptor, see the document Serving WebObjects.

WOAdaptor and the Request-Response Loop

A WebObjects application's request-response loop (or run loop) begins when the WOApplication receives a run message. Before the run method begins the loop, it traverses its list of adaptors and sends each one of them a registerForEvents message. The registerForEvents method performs all tasks necessary to ensure that the WOAdaptor can begin receiving events. When the application is being terminated, WOApplication traverses its list of adaptors again and issues an unregisterForEvents message to each one of them. This method undoes whatever was done in registerForEvents so that the WOAdaptor stops receiving events.

For example, WODefaultAdaptor uses a socket connection to communicate with the HTTP server. In its registerForEvents message, WODefaultAdaptor creates an NSFileHandle object to represent the socket, registers itself as an observer of the NSFileHandleConnectionAcceptedNotification, and sends acceptConnectionInBackgroundAndNotify to the NSFileHandle so that WODefaultAdaptor will be informed when a connection takes place. (For more information, see the NSFileHandle class specification in the Foundation Framework Reference.)

When WODefaultAdaptor receives the NSFileHandleConnectionAcceptedNotification, it reads the method lines, HTTP header information, and any HTTP content from the request message, and creates a WORequest object using initWithMethod:uri:httpVersion:headers:content:userInfo:.

After it has created the WORequest object, WODefaultAdaptor sends it to the WOApplication using the message handleRequest:. Upon receiving the request, WOApplication starts a request-response cycle. This cycle results in a response that must be sent back to the server. (That is, the handleRequest: message returns a WOResponse object.) WODefaultAdaptor receives the WOResponse and translates it into a message that it can send back to the adaptor.

In unregisterForEvents, WODefaultAdaptor simply releases its NSFileHandle object and removes itself as an observer of NSFileHandleConnectionAcceptedNotification so that it will stop receiving requests.

Although WODefaultAdaptor uses sockets as its means of communications, you can use any other means of communication available, such as Distributed Objects (with NSConnection objects), pipes, or ports.


INSTANCE METHODS

initWithName:arguments:application:

- (id)initWithName:(NSString *)aName arguments:(NSArray *)someArguments application:(WOApplication *)anApplication

Initializes a WOAdaptor with the name aName arguments someArguments, and application anApplication. aName is the name of the WOAdaptor subclass. someArguments is the argument list passed to the application. anApplication is the WOApplication instance with which this adaptor will be associated.

The WOApplication method adaptorWithName:arguments: invokes this message when it encounters an -a option on the command line. The WOApplication retains each of its WOAdaptors; therefore, the WOAdaptor must not retain the WOApplication instance anApplication, as it will cause a retain/release cycle. (That is, if WOApplication retains WOAdaptor and WOAdaptor retains WOApplication, neither will ever reach a retain count of 0, so neither will be released.)

See Also: - adaptorWithName:arguments: in WOApplication


registerForEvents

- (void)registerForEvents

Performs any actions necessary to have the WOAdaptor start receiving events. See WOAdaptor and the Request-Response Loop in the Class Description above for an example.

See Also: - runloop in WOApplication


unregisterForEvents

- (void)unregisterForEvents

Undoes the actions performed in registerForEvents so that the WOAdaptor stops receiving events. See WOAdaptor and the Request-Response Loop in the Class Description above for an example.