org.osid.transport

Interface Summary
Interface	Description
DataInputStream	The data input stream provides a means for reading data from a stream.
DataOutputStream	The data output stream provides a means in which data can be written to a stream.
Endpoint	An `Endpoint` represents a transport destination.
EndpointList	Like all `OsidLists,` `EndpointList` provides a means for accessing `Endpoint` elements sequentially either one at a time or many at a time.
EndpointLookupSession	This session provides methods for retrieving `Endpoint` objects.
InboundMessageSession	The inbound message session is used as a listener.
InboundStreamSession	The inbound stream session is used as a listener.
MessageReceiver	The `MessageReceiver` is used to receive incoming connections.
OutboundMessageSession	This session provides access to a request/response protocol provider.
OutboundStreamSession	The outbound stream session is used to send and receive arbitrary data to and from a remote end point.
Request	A `Request` represents a stuctured request to a service endpoint.
Response	A `Response` represents a stuctured response from a service endpoint.
StreamReceiver	The `StreamReceiver` is used to receive incoming connections.
TransportManager	This manager provides access to the sessions defined in this service.
TransportProfile	The `TransportProfile` defines the interoperability of the transport OSID.
TransportProxyManager	This manager provides access to the sessions defined in this service.

Package org.osid.transport Description

The Open Service Interface Definitions for the org.osid.transport service.

The transport OSID provides a means of moving data to or from the local endpoint.

Service Endpoints

The transport OSID defines an inbound and an outbound service. An outbound transport service is used from a local endpoint to a single remote endpoint. The remote endpoint may represent one or more physical endpoints, such as a multicast network, but presents itself as a single enpoint to the consumer. The inbound service is used to receive and process data from multiple remote endpoints and is implemented using a callback mechanism when a new request for association arrives.

An association or connection between two endpoints is represented by the session itself. The Transport OSID defines two flavors of transport. One is stream oriented that makes use of DataInputStream and DataOutputStream for reading and writing data. The other is message oriented that makes use of Request and Response for structuring data.

Stream-oriented Service

In the stream-oriented case, the transport OSID does not describe the format or sequence of the data which must be agreed upon at both ends. The OSID simply acts as a cover for specific transport or session related APIs, and provides a means for modular handling of service location for the purpose implementing a redundancy or load balancing scheme. The transport OSID may be used within another OSID to handle the transport of serialized data that can be transformed to a higher level OSID object.

The data streams defined in the transport OSID are also used in other OSIDs where a data stream is required such as the filing OSID or an Asset that contains arbitrary serialized data.

Message-oriented Service

The message oriented services provide additional structure that can be used to specify fields, organize streams, or provide data to object conversions. Requests may be sent synchronously so that each request waits for a Response, or asynchronously where each response is sent to a registered callback. A message Type describes both the structure of the Request and Response messages.

Outbound Example

      
      
      OutboundStreamSession session = manager.getOutboundStreamSession();
      
      // simplified example of handling an authenticated service within the streams 
      DataOutputStream auth = session.sendData();
      DataInputStream credential = authentication.getCredential(credentialViaStreamType);
      auth.writeStream(credential);
      DataInputStream authResponse = session.receiveData();
      
      // sending an rpc-style command in the stream
      DataOutputStream out = session.sendData();
      String cmd = "<call><command>getSongs</command><params><param>" + album + "</param></call>";
      out.write(cmd.length(), cmd);
      out.close();
      
      while(session.hasDataAvailable()) {
          DataInputStream in = session.receiveData();
          addSongToPlayQueue(in);
      }

Inbound Example

      
      
      public void dispatch(OutboundStreamSession session) {
          Authentication auth = authenticateSession(session.receiveData());
          if (authzSession.isAuthorized(auth.getAgentId, fId, qId)) {
              String argv = parseCommandFromStream(session.receiveData());
              if (argv[0].equals("getSongs")) {
                  Song songs = getSongsFromAlbum(argv[1]);
                  for (song: songs) {
                      DataOutputStream out = session.sendData();
                      out.write(song.data(), song.size());
                  }
              }
          }
      }

Message Example

      
      
      OutboundMessageSession session = manager.getOutboundMessageSession();
      
      Request request = session.getRequest();
      RequestHeader header = (HeaderRequestRecord) request.getRequestRecord(headerRequestRecordType);
      header.setAuthentication(authentication);
      // the message structure may also define interoperability cues 
      // for the consumer
      if (header.supportsLanguage()) {
          header.setLanguage(languageType);
      }
      
      Response response = session.makeRequest(request);
      
      if (response.ok()) {
          request = session.getRequest();
          ListSongsRequest cmd = (ListSongsRequestRecord) request.getRequestRecord(listSongsMessageType);
          cmd.setAlbum(albumName);
          response = session.makeRequest(request);
          if (response.ok()) {
              ListSongsResponse songs = (ListSongsResponseRecord) response.getResponseRecord(listSongsResponseRecordType);
      
              // the transport provider can return data in the message, or be used
              // to return usable objects as specified by its type
              for (Song song : songs.getSongs()) {
                  Audio.play(song);
              }
          } else error(response.getStatusMessage());
      } else error (response.getStatusMessage());

This Work is being provided by the copyright holder(s) subject to the following license. By obtaining, using and/or copying this Work, you agree that you have read, understand, and will comply with the following terms and conditions.

Permission to use, copy and distribute unmodified versions of this Work, for any purpose, without fee or royalty is hereby granted, provided that you include the above copyright notices and the terms of this license on ALL copies of the Work or portions thereof.

You may nodify or create Derivatives of this Work only for your internal purposes. You shall not distribute or transfer any such Derivative of this Work to any location or to any third party. For the purposes of this license, "Derivative" shall mean any derivative of the Work as defined in the United States Copyright Act of 1976, such as a translation or modification.

This Work and the information contained herein is provided on an "AS IS" basis WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE WORK OR THE USE OR OTHER DEALINGS IN THE WORK.

The export of software employing encryption technology may require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain such a license before exporting this Work.