one.world Documentation: Class SioResource

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

one.world.io
Class SioResource

java.lang.Object
  |
  +--one.world.core.Tuple
        |
        +--one.world.io.SioResource

All Implemented Interfaces:: Cloneable, Serializable

public class SioResource
extends Tuple

Implementation of a descriptor for a structured I/O resource. Structured I/O resources can be specified in two ways, (1) through a descriptor as implemented by this class and (2) through a structured I/O URL. For convenience, this class implements a constructor that takes a structured I/O URL and generates the corresponding descriptor. It also implements a toString() method that returns a structured I/O URL corresponding to the structured I/O descriptor represented by an instance of this class.

Structured I/O URLs describe either tuple storage or the end-point of a communication channel. With the exception of relative paths for tuple storage, all structured I/O URLs start with the "sio:" protocol identifier, followed by "//". Relative paths start with the name of the first path segment.

Communication Channels

Structured I/O URLs for communication channels specify either a client or server end-point for a communication channel over TCP or an input-only, output-only, duplex, or multicast end-point for a communication channel over UDP. Structured I/O URLs for communication channels have the following form:

      sio://host[:port][?type=<client|server|input|output|
                               duplex|multicast>
                        [&local=host[:port]]
                        [&closure=text]
                        [&duration=number]]

The type attribute distinguishes between the six types of communication channel end-points. It may be omitted for client channels.

The host (and optional port number) for a communication channel specifies the local host (and port) for server and input channels and the remote host (and port) for client, output, duplex, and multicast channels. The local host (and port) for client and output channels can optionally be specified using the local attribute. The local host (and port) for duplex channels must be specified using the local attribute. If the local host is "localhost" for a server, input, or duplex channel, the channel will accept connections to any local IP address. To accept connections at the loopback interface, use "127.0.0.1" for the local host.

The closure and duration attributes specify the closure and initial lease duration for communication channels accepted on a server end-point. The value of the closure attribute is a string (even though the descriptor accepts arbitrary objects) and is encoded in the "x-www-form-urlencoded" MIME format. Both attributes are optional.

Omitted ports for communication channels are treated as the default port.

Storage

Structured I/O URLs for storage specify environments. Structured I/O URLs for storage can either be absolute, ID relative, or relative. Absolute and ID relative URLs have the following structure:

      sio://[host[:port]]/[path][?type=storage]

Relative URLs have the following structure:

      path

Paths are composed of one or more path segments, where each path segment is the name of an environment, the ID of an environment, "." for the current environment, or ".." for the parent environment, followed by a "/". When parsing structured I/O URLs for storage, path segments that represent an ID are treated as an ID while all other names (besides "." and "..") are treated as environment names.

Paths can be normalized by removing embedded "." path segments, collapsing "name/.." compound segments, and removing all segments leading to an ID. The normalized path for an absolute URL must not contain ".", "..", or an ID. The normalized path for an ID relative URL must start with an ID, followed by zero or more ".." path segments, followed by zero or more environment names. The normalized path for a relative URL either is "." or consists of zero or more ".." path segments followed by zero or more environment names.

The type attribute can generally be omitted, though it must be present for structured I/O URLs of the form sio://host[:port], because such URLs are otherwise interpreted as URLs describing client end-points for communication channels.

Binding Requests and Responses

When using a structured I/O resource descriptor in a binding request, the corresponding binding response returns an event handler for the structured I/O resource. The types of structured I/O requests accepted by the returned event handler depend on the type of structured I/O resource. They are as following:

A client communication channel accepts simple input requests and simple output requests.
A server communication channel accepts no structured I/O requests. Rather, additional binding responses are generated when the underlying TCP server socket accepts a connection and the server is bound to a client. The event handler returned through such an additional binding response accepts simple input and output requests.
An input communication channel accepts only simple input requests.
An output communication channel accepts only simple output requests.
Duplex and multicast communication channels accept both simple input and output requests.
Storage not only accepts simple input and output requests, but also input requests, output requests, and delete requests.

Version:: $Revision: 1.13 $
See Also:: Serialized Form

Field Summary

static int CLIENT
          The type code for a client end-point of a structured I/O communication channel over TCP.

Object closure
          The closure for server end-points.

static int DUPLEX
          The type code for a duplex end-point of a structured I/O communication channel over UDP.

long duration
          The default lease duration for communication channels accepted on a server end-point.

Guid ident
          The environment ID for tuple storage.

static int INPUT
          The type code for an input-only end-point of a structured I/O communication channel over UDP.

String localHost
          The local host.

int localPort
          The local port.

static int MULTICAST
          The type code for a multicast end-point of a structured I/O communication channel over UDP.

static int OUTPUT
          The type code for an output-only end-point of a structured I/O communication channel over UDP.

String[] path
          The path for tuple storage, broken up into individual path segments.

String remoteHost
          The remote host.

int remotePort
          The remote port.

static int SERVER
          The type code for a server end-point of a structured I/O communication channel over TCP.

static int STORAGE
          The type code for tuple storage as provided by an environment.

int type
          The type of structured I/O resource described by this structured I/O resource descriptor.

Fields inherited from class one.world.core.Tuple

CLOSURE, id, ID, META_DATA, metaData, SOURCE

Constructor Summary

SioResource()
          Create a new, empty structured I/O resource descriptor.

SioResource(String url)
          Create a new structured I/O resource descriptor from the specified string specification.

Method Summary

boolean isAbsolute()
          Determine whether this structured I/O resource descriptor represents an absolute path to tuple storage.

boolean isIdRelative()
          Determine whether this structured I/O resource descriptor represents an ID relative path to tuple storage.

boolean isRelative()
          Determine whether this structured I/O resource descriptor represents a relative path to tuple storage.

String toString()
          Get a structured I/O URL corresponding to this descriptor for a structured I/O resource.

void validate()
          Validate this structured I/O resource descriptor.

static void validateHost(String host)
          Validate the specified host name.

static void validatePort(int port)
          Validate the specified port number.

Methods inherited from class one.world.core.Tuple

clone, containsNonSymbolicHandler, equals, fields, get, getMetaData, getType, hasField, hashCode, hasMetaData, remove, set, setMetaData, wrap

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

STORAGE

public static final int STORAGE

The type code for tuple storage as provided by an environment. A descriptor of this type must specify at least an environment by its ID, an absolute path, a relative path, or a path relative to an ID. It may also specify a remote host and port.

CLIENT

public static final int CLIENT

The type code for a client end-point of a structured I/O communication channel over TCP. A descriptor of this type must at least specify the remote host and port, though it may also specify the local host and port.

SERVER

public static final int SERVER

The type code for a server end-point of a structured I/O communication channel over TCP. A descriptor of this type must specify the local host and port.

INPUT

public static final int INPUT

The type code for an input-only end-point of a structured I/O communication channel over UDP. A descriptor of this type must specify the local host and port.

OUTPUT

public static final int OUTPUT

The type code for an output-only end-point of a structured I/O communication channel over UDP. A descriptor of this type must specify at least the remote host and port, though it may also specify the local host and port.

DUPLEX

public static final int DUPLEX

The type code for a duplex end-point of a structured I/O communication channel over UDP. A descriptor of this type must specify both the local and the remote hosts and ports.

MULTICAST

public static final int MULTICAST

The type code for a multicast end-point of a structured I/O communication channel over UDP. A descriptor of this type must specify the remote host and port.

type

public int type

The type of structured I/O resource described by this structured I/O resource descriptor.

ident

public Guid ident

The environment ID for tuple storage.

path

public String[] path

The path for tuple storage, broken up into individual path segments. If this path is absolute, the first entry in the array must be "/".

localHost

public String localHost

The local host.

localPort

public int localPort

The local port.

remoteHost

public String remoteHost

The remote host.

remotePort

public int remotePort

The remote port.

closure

public Object closure

The closure for server end-points.

duration

public long duration

The default lease duration for communication channels accepted on a server end-point.

Constructor Detail

SioResource

public SioResource()

Create a new, empty structured I/O resource descriptor.

SioResource

public SioResource(String url)

Create a new structured I/O resource descriptor from the specified string specification.

Parameters:: url - The structured I/O URL for the new structured I/O resource descriptor.
Throws:: IllegalArgumentException - Signals a malformed structured I/O URL.

Method Detail

isAbsolute

public boolean isAbsolute()

Determine whether this structured I/O resource descriptor represents an absolute path to tuple storage.

Returns:: true if this structured I/O resource descriptor represents an absolute path to tuple storage.

isRelative

public boolean isRelative()

Determine whether this structured I/O resource descriptor represents a relative path to tuple storage.

Returns:: true if this structured I/O resource descriptor represents a relative path to tuple storage.

isIdRelative

public boolean isIdRelative()

Determine whether this structured I/O resource descriptor represents an ID relative path to tuple storage.

Returns:: true if this structured I/O resource descriptor represents an ID relative path to tuple storage.

validate

public void validate()
              throws TupleException

Validate this structured I/O resource descriptor.

Overrides:: validate in class Tuple

Following copied from class: one.world.core.Tuple

Throws:: TupleException - Signals that the tuple is either malformed (i.e., does not conform to the tuple specification) or invalid (i.e., does not conform to the semantic constraints of its type).
See Also:: MalformedTupleException, InvalidTupleException, Type.validate(Class)

validateHost

public static void validateHost(String host)
                         throws InvalidTupleException

Validate the specified host name.

Parameters:: host - The host.
Throws:: InvalidTupleException - Signals that the specified host is null or contains an invalid character.

validatePort

public static void validatePort(int port)
                         throws InvalidTupleException

Validate the specified port number.

Parameters:: port - The port number.
Throws:: InvalidTupleException - Signals that the specified port number is invalid.

toString

public String toString()

Get a structured I/O URL corresponding to this descriptor for a structured I/O resource. Invoking this method on an invalid descriptor may produce a malformed structured I/O URL.

Overrides:: toString in class Tuple

Following copied from class: one.world.core.Tuple

Returns:: A string representation for this tuple.

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: INNER | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

Field Summary
`static int`	`CLIENT` The type code for a client end-point of a structured I/O communication channel over TCP.
`Object`	`closure` The closure for server end-points.
`static int`	`DUPLEX` The type code for a duplex end-point of a structured I/O communication channel over UDP.
`long`	`duration` The default lease duration for communication channels accepted on a server end-point.
`Guid`	`ident` The environment ID for tuple storage.
`static int`	`INPUT` The type code for an input-only end-point of a structured I/O communication channel over UDP.
`String`	`localHost` The local host.
`int`	`localPort` The local port.
`static int`	`MULTICAST` The type code for a multicast end-point of a structured I/O communication channel over UDP.
`static int`	`OUTPUT` The type code for an output-only end-point of a structured I/O communication channel over UDP.
`String[]`	`path` The path for tuple storage, broken up into individual path segments.
`String`	`remoteHost` The remote host.
`int`	`remotePort` The remote port.
`static int`	`SERVER` The type code for a server end-point of a structured I/O communication channel over TCP.
`static int`	`STORAGE` The type code for tuple storage as provided by an environment.
`int`	`type` The type of structured I/O resource described by this structured I/O resource descriptor.

Constructor Summary
`SioResource()` Create a new, empty structured I/O resource descriptor.
`SioResource(String url)` Create a new structured I/O resource descriptor from the specified string specification.

Method Summary
`boolean`	`isAbsolute()` Determine whether this structured I/O resource descriptor represents an absolute path to tuple storage.
`boolean`	`isIdRelative()` Determine whether this structured I/O resource descriptor represents an ID relative path to tuple storage.
`boolean`	`isRelative()` Determine whether this structured I/O resource descriptor represents a relative path to tuple storage.
`String`	`toString()` Get a structured I/O URL corresponding to this descriptor for a structured I/O resource.
`void`	`validate()` Validate this structured I/O resource descriptor.
`static void`	`validateHost(String host)` Validate the specified host name.
`static void`	`validatePort(int port)` Validate the specified port number.

one.world.io Class SioResource

STORAGE

CLIENT

SERVER

INPUT

OUTPUT

DUPLEX

MULTICAST

type

ident

path

localHost

localPort

remoteHost

remotePort

closure

duration

SioResource

SioResource

isAbsolute

isRelative

isIdRelative

validate

validateHost

validatePort

toString

one.world.io
Class SioResource