Because the bulk of the work is done within the SOAP::Lite module itself, many of the transport-level modules are very simple in their implementations . Transport modules are expected to define both client and server classes within their files. If a module defines only one of the types, it is assumed that the transport protocol itself supports only that side of the conversation. An example is SOAP::Transport::FTP , which provides only a SOAP::Transport::FTP::Client class. Each class is expected to declare (or inherit, if it is subclassing another transport class) at least two methods . Any newly developed transport classes is also expected to adhere to this interface. Here are the methods:
Each individual transport module is now examined, and their provision of client and/or server classes is outlined. Each class detailed also includes notes on which of the classes from SOAP::Lite they inherit from, for reference. B.2.1 SOAP::Transport::FTPThe SOAP::Transport::FTP module is automatically loaded by the SOAP::Transport portion of the client structure. It is brought in when an endpoint is specified via the proxy method that starts with the characters , ftp:// . This module provides only a client class. B.2.1.1 SOAP::Transport::FTP::ClientInherits from: SOAP::Client . Support is provided for clients to connect to FTP servers using SOAP. The methods defined within the class are just the basic new and send_receive . B.2.2 SOAP::Transport::HTTPThe most commonly used transport module is the HTTP implementation. This is loaded whenever an endpoint is given that starts with the characters, http:// or https :// . This is also the most involved of the transport modules, defining not only a client class but several different server classes as well. B.2.2.1 SOAP::Transport::HTTP::ClientInherits from: SOAP::Client , LWP::UserAgent (from the LWP package). With this class, clients are able to use HTTP for sending messages. This class provides just the basic new and send_receive methods. Objects of this class understand the compress_threshold option and use it if the server being communicated to also understands it. B.2.2.2 SOAP::Transport::HTTP::ServerInherits from: SOAP::Server . This is the most basic of the HTTP server implementations. It provides the basic methods, new and handle . The handle method's behavior is defined here, along with other methods specific to this class. The role of this class is primarily to act as a superclass for the other HTTP-based server classes.
B.2.2.3 SOAP::Transport::HTTP::CGIInherits from: SOAP::Transport::HTTP::Server . This class is a direct subclass of SOAP::Transport::HTTP::Server and defines no additional methods. It includes logic in its implementation of the handle method that deals with the request headers and parameters specific to a CGI environment. B.2.2.4 SOAP::Transport::HTTP::DaemonInherits from: SOAP::Transport::HTTP::Server . The SOAP::Transport::HTTP::Daemon class encapsulates a reference to an object of the HTTP::Daemon class (from the LWP package). The class catches methods that aren't provided locally or by the superclass and attempts to call them on the HTTP::Daemon object. Thus, all methods defined in the documentation for that class are available to this class as well. Any that conflict with methods in SOAP::Transport::HTTP::Server (such as product_tokens ) go to the superclass. Additionally, the behavior of the handle method is specific to this class:
B.2.2.5 SOAP::Transport::HTTP::ApacheInherits from: SOAP::Transport::HTTP::Server . This class provides an integration of the SOAP::Server base class with the mod_perl extension for Apache. To work as a location handler, the package provides a method called handler , for which handle is made an alias. The new method isn't functionally different from the superclass. Here are the other methods provided by this class:
B.2.2.6 SOAP::Transport::HTTP::FCGIInherits from: SOAP::Transport::HTTP::CGI . This is an extension of the SOAP::Transport::HTTP::CGI that implements the differences needed for the FastCGI protocol. None of the methods are functionally different. B.2.3 SOAP::Transport::IOThe SOAP::Transport::IO -based class allows for a sort of I/O proxying by allowing the application to configure what files or filehandles are used. This module supplies only a server class. B.2.3.1 SOAP::Transport::IO::ServerInherits from: SOAP::Server . The server class defined here inherits all methods from SOAP::Server , and adds two additional methods specific to the nature of the class:
B.2.4 SOAP::Transport::JABBERThis class uses the Net::Jabber classes to abstract the Jabber protocol away from the direct notice of the application. Besides maintaining any needed objects internally, the package also uses a separate class as a proxy between communication layers , SOAP::Transport::JABBER::Query . The Jabber support provides both client and server classes. B.2.4.1 SOAP::Transport::JABBER::ClientInherits from: SOAP::Client , Net::Jabber::Client . This class provides localized implementations for both the new and send_receive methods, neither of which are changed in terms of interface. The only difference is that the send_receive method doesn't directly use the action hash key on the input it receives. In addition to these two basic methods, the server class overrides the endpoint method it would otherwise inherit from SOAP::Client :
B.2.4.2 SOAP::Transport::JABBER::ServerInherits from: SOAP::Server . The server class provided for Jabber support defines a slightly different interface to the constructor. The server manages the Jabber communication by means of an internal Net::Jabber::Client instance. In a fashion similar to that used by SOAP::Transport::HTTP::Daemon , the server class catches methods that are meant for the Jabber client and treats them as if the class inherits directly from that class, without actually doing so. In doing so, the handle method is implemented as a frontend to the Process method of the Jabber client class. The difference in the interface to the constructor is:
B.2.5 SOAP::Transport::LOCALThe SOAP::Transport::LOCAL module is designed to provide a no-transport client class for tracing and debugging communications traffic. It links SOAP::Client and SOAP::Server so that the same object that "sends" the request also "receives" it. B.2.5.1 SOAP::Transport::LOCAL::ClientInherits from: SOAP::Client , SOAP::Server . The implementations of the new and send_receive methods aren't noticeably different in their interface. Their behavior warrants description, however:
B.2.6 SOAP::Transport::MAILTOThis transport class manages SMTP-based sending of messages from a client perspective. It doesn't provide a server class. The class gets selected when a client object passes a URI to proxy or endpoint that starts with the characters, mailto: . B.2.6.1 SOAP::Transport::MAILTO::ClientInherits from: SOAP::Client . The client class for this protocol doesn't define any new methods. The constructor functions in the same style as the others class constructors. The functionality of the send_receive method is slightly different from other classes, however. When invoked, the send_receive method uses the MIME::Lite package to encapsulate and transmit the message. Because mail messages are one-way communications (the reply being a separate process), there is no response message to be returned by the method. Instead, all the status-related attributes ( code , message , status , is_success ) are set, and no value is explicitly returned. B.2.7 SOAP::Transport::MQThis class provides implementations of both client and server frameworks built on IBM's Message Queue set of classes. The SOAP objects encapsulate additional objects from these classes, creating and using them behind the scenes as needed. B.2.7.1 SOAP::Transport::MQ::ClientInherits from: SOAP::Client . The client class provides two methods specific to it, as well as specialized versions of the endpoint and send_receive methods. It also provides a localized new method, but the interface isn't changed from the superclass method. The new methods are:
The two previous methods are mainly used by the localized versions of the methods:
B.2.7.2 SOAP::Transport::MQ::ServerInherits from: SOAP::Server . The server class also defines requestqueue and replyqueue methods under the same terms as the client class. Of course, the server reads from the request queue and writes to the reply queue, the opposite of the client's behavior. The methods whose functionality are worth noting are:
B.2.8 SOAP::Transport::POP3POP3 support is limited to a server implementation. Just as the MAILTO class detailed earlier operates by sending requests without expecting to process a response, the server described here accepts request messages and dispatches them without regard for sending a response other than that which POP3 defines for successful delivery of a message. B.2.8.1 SOAP::Transport::POP3::ServerInherits from: SOAP::Server . The new method of this class creates an object of the Net::POP3 class to use internally for polling a specified POP3 server for incoming messages. When an object of this class is created, it expects an endpoint to be specified with a URI that begins with the characters pop:// and includes user ID and password information as well as the hostname itself. The handle method takes the messages present in the remote mailbox and passes them (one at a time) to the superclass handle method. Each message is deleted after being routed. All messages in the POP3 mailbox are presumed to be SOAP messages. Methods for the Net::POP3 object are detected and properly routed, allowing operations such as $server->ping( ) . This means that the endpoint string doesn't need to provide the user ID and password because the login method from the POP3 API may be used directly. B.2.9 SOAP::Transport::TCPThe classes provided by this module implement direct TCP/IP communications methods for both clients and servers. The connections don't use HTTP or any other higher-level protocol. These classes are selected when the client or server object being created uses an endpoint URI that starts with tcp:// . Both client and server classes support using Secure Socket Layer if it is available. If any of the parameters to a new method from either of the classes begins with SSL_ (such as SSL_server in place of Server ), the class attempts to load the IO::Socket::SSL package and use it to create socket objects. Both of the following classes catch methods that are intended for the socket objects and pass them along, allowing calls such as $client->accept( ) without including the socket class in the inheritance tree. B.2.9.1 SOAP::Transport::TCP::ClientInherits from: SOAP::Client . The TCP client class defines only two relevant methods beyond new and send_receive . These methods are:
If an application creates a subclass that inherits from this client class, either method is a likely target for overloading. The new method behaves identically to most other classes, except that it detects the presence of SSL- targeted values in the parameter list and sets the SSL method appropriately if they are present. The send_receive method creates a socket of the appropriate class and connects to the configured endpoint. It then sets the socket to nonblocking I/O, sends the message, shuts down the client end of the connection (preventing further writing), and reads the response back from the server. The socket object is discarded after the response and appropriate status codes are set on the client object. B.2.9.2 SOAP::Transport::TCP::ServerInherits from: SOAP::Server . The server class also defines the same two additional methods as in the client class:
The new method also manages the automatic selection of SSL in the same fashion as the client class does. The handle method in this server implementation isn't designed to be called once with each new request. Rather, it is called with no arguments, at which time it enters into an infinite loop of waiting for a connection, reading the request, routing the request and sending back the serialized response. This continues until the process itself is interrupted by an untrapped signal or similar means. |