Author: david.lloyd(a)jboss.com Date: 2008-06-30 23:07:01 -0400 (Mon, 30 Jun 2008) New Revision: 4334 Added: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/marshal/package-info.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/package-info.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/package-info.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/package-info.java Removed: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/UnknownIdentifierException.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/Registration.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/protocol/ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/RemoteStreamSerializer.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/StreamContext.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/StreamSerializer.java Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/AbstractRequestListener.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/Client.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/ClientContext.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/ClientSource.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/CloseHandler.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/Closeable.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/Endpoint.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/FutureReply.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/IOExceptionCarrier.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/IndeterminateOutcomeException.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RemoteExecutionException.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RemotingException.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RemotingExceptionCarrier.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RequestCancelHandler.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RequestCompletionHandler.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RequestContext.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RequestListener.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/ServiceContext.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/Session.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/SessionListener.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/service/package-info.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/marshal/CompositeObjectResolver.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/marshal/Marshaller.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/marshal/MarshallerFactory.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/StreamDetector.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/StreamSerializerFactory.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/ClientSourceWrapper.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/ClientWrapper.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/EndpointWrapper.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/RequestContextWrapper.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/SessionWrapper.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/ObjectSink.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/ObjectSinkWrapper.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/ObjectSource.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/ObjectSourceWrapper.java remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/Streams.java Log: Another big API overhaul. This one will break things for a while. Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/AbstractRequestListener.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/AbstractRequestListener.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/AbstractRequestListener.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -1,18 +1,31 @@ package org.jboss.cx.remoting; /** - * + * A simple request listener implementation that implements all methods with no-operation implementations. */ public abstract class AbstractRequestListener<I, O> implements RequestListener<I, O> { + + /** + * {@inheritDoc} This implementation performs no operation. + */ public void handleClientOpen(final ClientContext context) { } + /** + * {@inheritDoc} This implementation performs no operation. + */ public void handleServiceOpen(final ServiceContext context) { } + /** + * {@inheritDoc} This implementation performs no operation. + */ public void handleServiceClose(final ServiceContext context) { } + /** + * {@inheritDoc} This implementation performs no operation. + */ public void handleClientClose(final ClientContext context) { } } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/Client.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/Client.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/Client.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -4,6 +4,9 @@ /** * A communications client. The client may be associated with state maintained by the local and/or remote side. + * + * @param <I> the request type + * @param <O> the reply type */ public interface Client<I, O> extends Closeable<Client<I, O>> { /** Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/ClientContext.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/ClientContext.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/ClientContext.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -3,7 +3,7 @@ import java.util.concurrent.ConcurrentMap; /** - * + * The server context for a single remote client instance. */ public interface ClientContext extends Closeable<ClientContext> { /** Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/ClientSource.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/ClientSource.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/ClientSource.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -2,6 +2,9 @@ /** * A source for new Remoting contexts. + * + * @param <I> the request type + * @param <O> the reply type */ public interface ClientSource<I, O> extends Closeable<ClientSource<I, O>> { /** Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/CloseHandler.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/CloseHandler.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/CloseHandler.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -1,8 +1,16 @@ package org.jboss.cx.remoting; /** + * A handler which is notified of a resource close. * + * @param <T> the type of resource */ public interface CloseHandler<T> { + + /** + * Receive a notification that the resource was closed. + * + * @param closed the closed resource + */ void handleClose(T closed); } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/Closeable.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/Closeable.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/Closeable.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -1,7 +1,9 @@ package org.jboss.cx.remoting; /** + * A Remoting resource that can be closed. * + * @param <T> the type that is passed to the close handler */ public interface Closeable<T> extends java.io.Closeable { // TODO - do we need an async close method? Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/Endpoint.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/Endpoint.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/Endpoint.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -2,10 +2,6 @@ import java.net.URI; import java.util.concurrent.ConcurrentMap; -import org.jboss.cx.remoting.spi.Registration; -import org.jboss.cx.remoting.spi.protocol.ProtocolContext; -import org.jboss.cx.remoting.spi.protocol.ProtocolHandler; -import org.jboss.cx.remoting.spi.protocol.ProtocolHandlerFactory; import org.jboss.cx.remoting.util.AttributeMap; /** @@ -41,17 +37,6 @@ Session openSession(URI remoteUri, AttributeMap attributeMap, RequestListener<?, ?> rootListener) throws RemotingException; /** - * Open an inbound session from another endpoint. Used by protocol handlers. - * - * You must have the TODO permission to invoke this method. - * - * @param handler the protocol handler to use - * @param rootListener the root request listener for this end of the session - * @return the protocol context - */ - ProtocolContext openSession(ProtocolHandler handler, RequestListener<?, ?> rootListener) throws RemotingException; - - /** * Get the name of this endpoint. * * @return the endpoint name, or {@code null} if there is no name @@ -59,20 +44,6 @@ String getName(); /** - * Register a protocol specification for this endpoint. - * - * You must have the TODO permission to invoke this method. - * - * @param scheme the URI scheme - * @param protocolHandlerFactory the protocol handler factory - * @return a registration that may be used to control this deployment - * - * @throws RemotingException if the protocol registration failed - * @throws IllegalArgumentException if the specification failed validation - */ - Registration registerProtocol(String scheme, ProtocolHandlerFactory protocolHandlerFactory) throws RemotingException, IllegalArgumentException; - - /** * Create a client that can be used to invoke a request listener on this endpoint. The client may be passed to a * remote endpoint as part of a request or a reply, or it may be used locally. * Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/FutureReply.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/FutureReply.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/FutureReply.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -9,6 +9,8 @@ * <p/> * In addition to representing the invocation results, this interface allows the user to cancel the request, or schedule * an asynchronous callback for when the request completes. + * + * @param <T> the result type of the future operation */ public interface FutureReply<T> extends Future<T> { Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/IOExceptionCarrier.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/IOExceptionCarrier.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/IOExceptionCarrier.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -3,13 +3,26 @@ import java.io.IOException; /** - * + * A runtime exception that carries an {@link java.io.IOException} as a cause. */ public class IOExceptionCarrier extends RuntimeException { + + private static final long serialVersionUID = -1602940590696531671L; + + /** + * Construct a new carrier. + * + * @param cause the nested cause + */ public IOExceptionCarrier(IOException cause) { super(cause); } + /** + * Get the cause. + * + * @return the cause + */ public IOException getCause() { return (IOException) super.getCause(); } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/IndeterminateOutcomeException.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/IndeterminateOutcomeException.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/IndeterminateOutcomeException.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -1,20 +1,47 @@ package org.jboss.cx.remoting; /** - * + * An exception that is thrown when an operation terminates in such a way that the outcome cannot be known. */ public class IndeterminateOutcomeException extends RemoteExecutionException { + + private static final long serialVersionUID = 6304843915977033800L; + + /** + * Constructs a <tt>IndeterminateOutcomeException</tt> with no detail message. The cause is not initialized, and may + * subsequently be initialized by a call to {@link #initCause(Throwable) initCause}. + */ public IndeterminateOutcomeException() { } + /** + * Constructs a <tt>IndeterminateOutcomeException</tt> with the specified detail message. The cause is not initialized, + * and may subsequently be initialized by a call to {@link #initCause(Throwable) initCause}. + * + * @param msg the detail message + */ public IndeterminateOutcomeException(String msg) { super(msg); } + /** + * Constructs a <tt>IndeterminateOutcomeException</tt> with the specified cause. The detail message is set to: + * <pre> + * (cause == null ? null : cause.toString())</pre> + * (which typically contains the class and detail message of <tt>cause</tt>). + * + * @param cause the cause (which is saved for later retrieval by the {@link #getCause()} method) + */ public IndeterminateOutcomeException(Throwable cause) { super(cause); } + /** + * Constructs a <tt>IndeterminateOutcomeException</tt> with the specified detail message and cause. + * + * @param msg the detail message + * @param cause the cause (which is saved for later retrieval by the {@link #getCause()} method) + */ public IndeterminateOutcomeException(String msg, Throwable cause) { super(msg, cause); } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RemoteExecutionException.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RemoteExecutionException.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RemoteExecutionException.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -3,25 +3,64 @@ import java.util.concurrent.ExecutionException; /** - * + * Exception thrown when execution of a remote operation fails for some reason. */ public class RemoteExecutionException extends ExecutionException { + private static final long serialVersionUID = 3580395686019440048L; + + /** + * Constructs a <tt>RemoteExecutionException</tt> with no detail message. + * The cause is not initialized, and may subsequently be + * initialized by a call to {@link #initCause(Throwable) initCause}. + */ public RemoteExecutionException() { } + /** + * Constructs a <tt>RemoteExecutionException</tt> with the specified detail + * message. The cause is not initialized, and may subsequently be + * initialized by a call to {@link #initCause(Throwable) initCause}. + * + * @param msg the detail message + */ public RemoteExecutionException(String msg) { super(msg); } + /** + * Constructs a <tt>RemoteExecutionException</tt> with the specified cause. + * The detail message is set to: + * <pre> + * (cause == null ? null : cause.toString())</pre> + * (which typically contains the class and detail message of + * <tt>cause</tt>). + * + * @param cause the cause (which is saved for later retrieval by the + * {@link #getCause()} method) + */ public RemoteExecutionException(Throwable cause) { super(cause); } + /** + * Constructs a <tt>RemoteExecutionException</tt> with the specified detail + * message and cause. + * + * @param msg the detail message + * @param cause the cause (which is saved for later retrieval by the + * {@link #getCause()} method) + */ public RemoteExecutionException(String msg, Throwable cause) { super(msg, cause); } + /** + * Rethrow the cause, if it is a runtime exception. This is a convenience method to extract a runtime exception + * from a remote execution exception. + * + * @throws RuntimeException the cause + */ public final void throwRuntime() throws RuntimeException { final Throwable cause = getCause(); if (cause instanceof RuntimeException) { Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RemotingException.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RemotingException.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RemotingException.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -3,39 +3,49 @@ import java.io.IOException; /** - * + * A general Remoting exception. */ public class RemotingException extends IOException { + + private static final long serialVersionUID = 1540716301579397423L; + + /** + * Constructs a <tt>RemotingException</tt> with no detail message. The cause is not initialized, and may subsequently be + * initialized by a call to {@link #initCause(Throwable) initCause}. + */ public RemotingException() { } - public RemotingException(String s) { - super(s); + /** + * Constructs a <tt>RemotingException</tt> with the specified detail message. The cause is not initialized, and may + * subsequently be initialized by a call to {@link #initCause(Throwable) initCause}. + * + * @param msg the detail message + */ + public RemotingException(String msg) { + super(msg); } - public RemotingException(String s, Throwable cause) { - super(getCauseString(s, cause)); - setStackTrace(cause.getStackTrace()); + /** + * Constructs a <tt>RemotingException</tt> with the specified cause. The detail message is set to: + * <pre> + * (cause == null ? null : cause.toString())</pre> + * (which typically contains the class and detail message of <tt>cause</tt>). + * + * @param cause the cause (which is saved for later retrieval by the {@link #getCause()} method) + */ + public RemotingException(Throwable cause) { + initCause(cause); } - public RemoteExecutionException getExecutionException() { - final RemoteExecutionException ex = new RemoteExecutionException(getMessage(), this); - ex.setStackTrace(getStackTrace()); - return ex; + /** + * Constructs a <tt>RemotingException</tt> with the specified detail message and cause. + * + * @param msg the detail message + * @param cause the cause (which is saved for later retrieval by the {@link #getCause()} method) + */ + public RemotingException(String msg, Throwable cause) { + super(msg); + initCause(cause); } - - private static String getCauseString(String ourMsg, Throwable cause) { - final String message = cause.getMessage(); - final String className = cause.getClass().getName(); - final StringBuilder builder = new StringBuilder(40); - builder.append(ourMsg); - builder.append(" (Caused by an exception of type "); - builder.append(className); - if (message != null) { - builder.append(" with message: "); - builder.append(message); - } - builder.append(")"); - return builder.toString(); - } } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RemotingExceptionCarrier.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RemotingExceptionCarrier.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RemotingExceptionCarrier.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -1,13 +1,26 @@ package org.jboss.cx.remoting; /** - * + * A runtime exception that carries a {@link org.jboss.cx.remoting.RemotingException} as a cause. */ public class RemotingExceptionCarrier extends IOExceptionCarrier { + + private static final long serialVersionUID = -1326735788761007331L; + + /** + * Construct a new carrier. + * + * @param cause the nested cause + */ public RemotingExceptionCarrier(RemotingException cause) { super(cause); } + /** + * Get the cause. + * + * @return the cause + */ public RemotingException getCause() { return (RemotingException) super.getCause(); } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RequestCancelHandler.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RequestCancelHandler.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RequestCancelHandler.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -1,8 +1,17 @@ package org.jboss.cx.remoting; /** + * A handler for request listeners to receive a notification when a request was cancelled. * + * @param <O> the reply type */ public interface RequestCancelHandler<O> { + + /** + * Receive notification that the request was cancelled. + * + * @param requestContext the request context + * @param mayInterrupt the value of the cancellation {@code mayInterrupt} flag + */ void notifyCancel(RequestContext<O> requestContext, boolean mayInterrupt); } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RequestCompletionHandler.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RequestCompletionHandler.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RequestCompletionHandler.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -1,8 +1,16 @@ package org.jboss.cx.remoting; /** + * A handler for receiving notification of request completion on the client side. * + * @param <T> the reply type */ public interface RequestCompletionHandler<T> { + + /** + * Receive notification that the request was completed, was cancelled, or has failed. + * + * @param futureReply the future result + */ void notifyComplete(FutureReply<T> futureReply); } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RequestContext.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RequestContext.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RequestContext.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -4,6 +4,8 @@ /** * The context of a single request. + * + * @param <O> the reply type */ public interface RequestContext<O> extends Executor { /** @@ -52,7 +54,7 @@ * Add a notifier to be called if a cancel request is received. The notifier may be called from the current thread * or a different thread. If the request has already been cancelled, the notifier will be called immediately. * - * @param handler + * @param handler the cancel handler */ void addCancelHandler(RequestCancelHandler<O> handler); Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RequestListener.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RequestListener.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/RequestListener.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -1,7 +1,10 @@ package org.jboss.cx.remoting; /** + * A request listener. Implementations of this interface will reply to client requests. * + * @param <I> the request type + * @param <O> the reply type */ public interface RequestListener<I, O> { /** @@ -44,7 +47,7 @@ /** * Handle the close of a client. * - * @param context + * @param context the client context */ void handleClientClose(ClientContext context); } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/ServiceContext.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/ServiceContext.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/ServiceContext.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -3,8 +3,15 @@ import java.util.concurrent.ConcurrentMap; /** - * + * The server-side context of a service. Used to hold state relating to a service (known as a {@code ContextSource} on + * the client side). */ public interface ServiceContext extends Closeable<ServiceContext> { + + /** + * Get an attribute map which can be used to cache arbitrary state on the server side. + * + * @return the attribute map + */ ConcurrentMap<Object, Object> getAttributes(); } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/Session.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/Session.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/Session.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -40,6 +40,8 @@ /** * Get the root client for this session. * + * @param <I> the request type + * @param <O> the reply type * @return the root client */ <I, O> Client<I, O> getRootClient(); Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/SessionListener.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/SessionListener.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/SessionListener.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -1,8 +1,14 @@ package org.jboss.cx.remoting; /** - * + * A session listener. Called when a session is opened on an endpoint. */ public interface SessionListener { + + /** + * Receive notification that the session was opened. + * + * @param session the new session + */ void handleSessionOpened(Session session); } Deleted: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/UnknownIdentifierException.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/UnknownIdentifierException.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/UnknownIdentifierException.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -1,17 +0,0 @@ -package org.jboss.cx.remoting; - -/** - * - */ -public class UnknownIdentifierException extends RemotingException { - public UnknownIdentifierException() { - } - - public UnknownIdentifierException(String msg) { - super(msg); - } - - public UnknownIdentifierException(String msg, Throwable cause) { - super(msg, cause); - } -} Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/service/package-info.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/service/package-info.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/service/package-info.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -1,4 +1,4 @@ /** * */ -package org.jboss.cx.remoting.service; \ No newline at end of file +package org.jboss.cx.remoting.service; Deleted: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/Registration.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/Registration.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/Registration.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -1,23 +0,0 @@ -package org.jboss.cx.remoting.spi; - -/** - * - */ -public interface Registration { - /** - * Activate this registration by placing it into the "started" state. In this state, - * no reconfiguration may be done. - */ - void start(); - - /** - * Deactivate this registration by placing it into the "stopped" state. In this state, the - * registration may be reconfigured. - */ - void stop(); - - /** - * Permanently remove this registration. Unreserves any resources associated with the registration. - */ - void unregister(); -} Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/marshal/CompositeObjectResolver.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/marshal/CompositeObjectResolver.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/marshal/CompositeObjectResolver.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -6,7 +6,7 @@ import org.jboss.cx.remoting.util.CollectionUtil; /** - * + * An object resolver that resolves objects by running through a fixed series of nested resolvers. */ public final class CompositeObjectResolver implements ObjectResolver { @@ -14,10 +14,19 @@ private final List<ObjectResolver> resolvers; + /** + * Construct a new composite resolver. The given list is copied. + * + * @param resolvers the resolver list + */ public CompositeObjectResolver(List<ObjectResolver> resolvers) { this.resolvers = Collections.unmodifiableList(CollectionUtil.arrayList(resolvers)); } + /** + * {@inheritDoc} This implementation runs through the series of nested resovlers and calls the {@code writeReplace} + * method on each. + */ public Object writeReplace(Object object) throws IOException { for (ObjectResolver resolver : resolvers) { object = resolver.writeReplace(object); @@ -25,6 +34,10 @@ return object; } + /** + * {@inheritDoc} This implementation runs through the series of nested resovlers and calls the {@code readResolve} + * method on each. + */ public Object readResolve(Object object) throws IOException { for (ObjectResolver resolver : CollectionUtil.reverse(resolvers)) { object = resolver.readResolve(object); Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/marshal/Marshaller.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/marshal/Marshaller.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/marshal/Marshaller.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -2,33 +2,36 @@ import java.io.IOException; import java.io.Serializable; -import org.jboss.cx.remoting.util.ObjectMessageInput; -import org.jboss.cx.remoting.util.ObjectMessageOutput; -import org.jboss.cx.remoting.util.ByteMessageOutput; -import org.jboss.cx.remoting.util.ByteMessageInput; +import java.nio.Buffer; +import org.jboss.cx.remoting.stream.ObjectSink; +import org.jboss.cx.remoting.stream.ObjectSource; /** * A marshaller/unmarshaller for transmitting data over a wire protocol of some sort. Each marshaller instance is * guaranteed to be used by only one thread. Marshallers are not pooled or reused in any way. Any pooling of marshallers * must be done by implementations of this class and/or {@link org.jboss.cx.remoting.spi.marshal.MarshallerFactory}. + * + * @param <T> the type of buffer that the marshaller uses, typically {@link java.nio.ByteBuffer} or {@link java.nio.CharBuffer} */ -public interface Marshaller extends Serializable { +public interface Marshaller<T extends Buffer> extends Serializable { /** - * Get a message writer that marshals to the given stream. + * Write objects to buffers. The buffers are allocated from the {@link org.jboss.xnio.BufferAllocator} that was + * provided to the {@link org.jboss.cx.remoting.spi.marshal.MarshallerFactory}. * - * @param byteMessageOutput the target stream - * @return the message writer - * @throws IOException if an error occurs + * @param bufferSink the sink for filled (and flipped) buffers + * @return a sink for objects + * @throws IOException if an error occurs while creating the marshaling sink */ - ObjectMessageOutput getMessageOutput(ByteMessageOutput byteMessageOutput) throws IOException; + ObjectSink<Object> getMarshalingSink(ObjectSink<T> bufferSink) throws IOException; /** - * Get a message reader that unmarshals from the given stream. + * Read objects from buffers. The buffers are freed to the {@link org.jboss.xnio.BufferAllocator} that was + * provided to the {@link org.jboss.cx.remoting.spi.marshal.MarshallerFactory}. * - * @param byteMessageInput the source stream - * @return the message reader - * @throws IOException if an error occurs + * @param bufferSource the source for filled (and flipped) buffers + * @return a source for objects + * @throws IOException if an error occurs while creating the unmarshaling source */ - ObjectMessageInput getMessageInput(ByteMessageInput byteMessageInput) throws IOException; + ObjectSource<Object> getUnmarshalingSource(ObjectSource<T> bufferSource) throws IOException; } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/marshal/MarshallerFactory.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/marshal/MarshallerFactory.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/marshal/MarshallerFactory.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -1,10 +1,24 @@ package org.jboss.cx.remoting.spi.marshal; import java.io.IOException; +import java.nio.Buffer; +import org.jboss.xnio.BufferAllocator; /** + * A factory to produce marshallers. * + * @param <T> the type of buffer that the marshaller uses, typically {@link java.nio.ByteBuffer} or {@link java.nio.CharBuffer} */ -public interface MarshallerFactory { - Marshaller createRootMarshaller(ObjectResolver resolver, ClassLoader classLoader) throws IOException; +public interface MarshallerFactory<T extends Buffer> { + + /** + * Create a marshaller instance. + * + * @param allocator the buffer allocator to use + * @param resolver the object resolver to use + * @param classLoader the classloader to use + * @return a marshaller + * @throws IOException if an error occurs while creating the marshaller + */ + Marshaller<T> createMarshaller(BufferAllocator<T> allocator, ObjectResolver resolver, ClassLoader classLoader) throws IOException; } Added: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/marshal/package-info.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/marshal/package-info.java (rev 0) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/marshal/package-info.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -0,0 +1,7 @@ +/** + * Classes related to marshalling. + * <p/> + * Due to the strangeness of the English language, we have "marshal", "marshaled", and "marshaling", yet we have + * "marshaller". + */ +package org.jboss.cx.remoting.spi.marshal; Deleted: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/RemoteStreamSerializer.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/RemoteStreamSerializer.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/RemoteStreamSerializer.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -1,8 +0,0 @@ -package org.jboss.cx.remoting.spi.stream; - -/** - * - */ -public interface RemoteStreamSerializer extends StreamSerializer { - Object getRemoteInstance(); -} Deleted: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/StreamContext.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/StreamContext.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/StreamContext.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -1,26 +0,0 @@ -package org.jboss.cx.remoting.spi.stream; - -import java.io.Closeable; -import java.io.IOException; -import org.jboss.cx.remoting.util.ObjectMessageOutput; - -/** - * - */ -public interface StreamContext extends Closeable { - - /** - * Write a message. The message is sent if/when the returned {@code MessageOutput} instance is committed. - * - * @return the message output instance - * @throws IOException if an error occurs - */ - ObjectMessageOutput writeMessage() throws IOException; - - /** - * Indicate that this stream is exhausted. - * - * @throws IOException if the notification did not succeed - */ - void close() throws IOException; -} Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/StreamDetector.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/StreamDetector.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/StreamDetector.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -6,7 +6,7 @@ public interface StreamDetector { /** * Detect a stream type. If the candidate is a stream type recognized by this detector, - * return the class of the factory to use. The factory class should have a no-arg constructor. + * return the factory to use. * * @param candidate the candidate object * @return the stream serializer factory, or {@code null} if this object is not recognized Deleted: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/StreamSerializer.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/StreamSerializer.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/StreamSerializer.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -1,31 +0,0 @@ -package org.jboss.cx.remoting.spi.stream; - -import java.io.IOException; -import org.jboss.cx.remoting.util.ObjectMessageInput; - -/** - * - */ -public interface StreamSerializer { - /** - * Handle the startup of the stream. - * - * @throws IOException if an error occurs - */ - void handleOpen() throws IOException; - - /** - * Handle an incoming message from the remote side. - * - * @param data the message - * @throws IOException if the stream data cannot be handled - */ - void handleData(ObjectMessageInput data) throws IOException; - - /** - * Handle a close from the remote side. - * - * @throws IOException if an error occurs - */ - void handleClose() throws IOException; -} Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/StreamSerializerFactory.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/StreamSerializerFactory.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/StreamSerializerFactory.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -1,12 +1,16 @@ package org.jboss.cx.remoting.spi.stream; +import org.jboss.xnio.IoHandler; +import org.jboss.xnio.Client; +import org.jboss.xnio.channels.StreamChannel; import java.io.IOException; +import java.io.Serializable; /** * */ -public interface StreamSerializerFactory { - StreamSerializer getLocalSide(StreamContext context, Object local) throws IOException; +public interface StreamSerializerFactory extends Serializable { + IoHandler<? super StreamChannel> getLocalSide(Object localSide) throws IOException; - RemoteStreamSerializer getRemoteSide(StreamContext context) throws IOException; + Object getRemoteSide(Client<StreamChannel> remoteClient) throws IOException; } Added: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/package-info.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/package-info.java (rev 0) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/stream/package-info.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -0,0 +1,4 @@ +/** + * Classes related to streaming. + */ +package org.jboss.cx.remoting.spi.stream; Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/ClientSourceWrapper.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/ClientSourceWrapper.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/ClientSourceWrapper.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -6,23 +6,40 @@ import org.jboss.cx.remoting.RemotingException; /** + * A simple delegating wrapper for client sources. * + * @param <I> the request type + * @param <O> the reply type */ public class ClientSourceWrapper<I, O> implements ClientSource<I, O> { private final ClientSource<I, O> delegate; + /** + * Construct a new instance. Calls will be sent to the given {@code delegate} by default. + * + * @param delegate the delegate client instance + */ protected ClientSourceWrapper(ClientSource<I, O> delegate) { this.delegate = delegate; } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public void close() throws RemotingException { delegate.close(); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public void closeImmediate() throws RemotingException { delegate.closeImmediate(); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public void addCloseHandler(final CloseHandler<ClientSource<I, O>> closeHandler) { delegate.addCloseHandler(new CloseHandler<ClientSource<I, O>>() { public void handleClose(final ClientSource<I, O> closed) { @@ -31,6 +48,9 @@ }); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public Client<I, O> createContext() throws RemotingException { return delegate.createContext(); } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/ClientWrapper.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/ClientWrapper.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/ClientWrapper.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -8,23 +8,40 @@ import org.jboss.cx.remoting.RemotingException; /** + * A simple delegating wrapper for clients. * + * @param <I> the request type + * @param <O> the reply type */ public class ClientWrapper<I, O> implements Client<I, O> { protected final Client<I, O> delegate; + /** + * Construct a new instance. Calls will be sent to the given {@code delegate} by default. + * + * @param delegate the delegate client instance + */ protected ClientWrapper(final Client<I, O> delegate) { this.delegate = delegate; } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public void close() throws RemotingException { delegate.close(); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public void closeImmediate() throws RemotingException { delegate.closeImmediate(); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public void addCloseHandler(final CloseHandler<Client<I, O>> closeHandler) { delegate.addCloseHandler(new CloseHandler<Client<I, O>>() { public void handleClose(final Client<I, O> closed) { @@ -33,22 +50,37 @@ }); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public O invoke(final I request) throws RemotingException, RemoteExecutionException { return delegate.invoke(request); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public FutureReply<O> send(final I request) throws RemotingException { return delegate.send(request); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public void sendOneWay(final I request) throws RemotingException { delegate.sendOneWay(request); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public ConcurrentMap<Object, Object> getAttributes() { return delegate.getAttributes(); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public ClassLoader getClassLoader() { return delegate.getClassLoader(); } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/EndpointWrapper.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/EndpointWrapper.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/EndpointWrapper.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -9,54 +9,68 @@ import org.jboss.cx.remoting.RequestListener; import org.jboss.cx.remoting.Session; import org.jboss.cx.remoting.SessionListener; -import org.jboss.cx.remoting.spi.Registration; -import org.jboss.cx.remoting.spi.protocol.ProtocolContext; -import org.jboss.cx.remoting.spi.protocol.ProtocolHandler; -import org.jboss.cx.remoting.spi.protocol.ProtocolHandlerFactory; import org.jboss.cx.remoting.util.AttributeMap; /** - * + * A simple delegating wrapper for endpoints. */ public class EndpointWrapper implements Endpoint { protected final Endpoint delegate; - protected EndpointWrapper(final Endpoint endpoint) { - delegate = endpoint; + /** + * Construct a new instance. Calls will be sent to the given {@code delegate} by default. + * + * @param delegate the delegate client instance + */ + protected EndpointWrapper(final Endpoint delegate) { + this.delegate = delegate; } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public ConcurrentMap<Object, Object> getAttributes() { return delegate.getAttributes(); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public Session openSession(final URI remoteUri, final AttributeMap attributeMap, final RequestListener<?, ?> rootListener) throws RemotingException { return delegate.openSession(remoteUri, attributeMap, rootListener); } - public ProtocolContext openSession(final ProtocolHandler handler, final RequestListener<?, ?> rootListener) throws RemotingException { - return delegate.openSession(handler, rootListener); - } - + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public String getName() { return delegate.getName(); } - public Registration registerProtocol(String scheme, ProtocolHandlerFactory protocolHandlerFactory) throws RemotingException, IllegalArgumentException { - return delegate.registerProtocol(scheme, protocolHandlerFactory); - } - + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public <I, O> Client<I, O> createClient(final RequestListener<I, O> requestListener) { return delegate.createClient(requestListener); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public <I, O> ClientSource<I, O> createService(final RequestListener<I, O> requestListener) { return delegate.createService(requestListener); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public void addSessionListener(final SessionListener sessionListener) { delegate.addSessionListener(sessionListener); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public void removeSessionListener(final SessionListener sessionListener) { delegate.removeSessionListener(sessionListener); } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/RequestContextWrapper.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/RequestContextWrapper.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/RequestContextWrapper.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -6,39 +6,67 @@ import org.jboss.cx.remoting.ClientContext; /** + * A simple delegating wrapper for request context instances. * + * @param <O> the reply type */ public class RequestContextWrapper<O> implements RequestContext<O> { protected final RequestContext<O> delegate; + /** + * Construct a new instance. Calls will be sent to the given {@code delegate} by default. + * + * @param delegate the delegate client instance + */ protected RequestContextWrapper(final RequestContext<O> delegate) { this.delegate = delegate; } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public ClientContext getContext() { return delegate.getContext(); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public boolean isCancelled() { return delegate.isCancelled(); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public void sendReply(O reply) throws RemotingException, IllegalStateException { delegate.sendReply(reply); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public void sendFailure(String msg, Throwable cause) throws RemotingException, IllegalStateException { delegate.sendFailure(msg, cause); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public void sendCancelled() throws RemotingException, IllegalStateException { delegate.sendCancelled(); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public void addCancelHandler(final RequestCancelHandler<O> requestCancelHandler) { delegate.addCancelHandler(requestCancelHandler); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public void execute(final Runnable command) { delegate.execute(command); } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/SessionWrapper.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/SessionWrapper.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/SessionWrapper.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -7,23 +7,37 @@ import org.jboss.cx.remoting.Session; /** - * + * A simple delegating wrapper for clients. */ public class SessionWrapper implements Session { protected final Session delegate; + /** + * Construct a new instance. Calls will be sent to the given {@code delegate} by default. + * + * @param delegate the delegate client instance + */ protected SessionWrapper(final Session delegate) { this.delegate = delegate; } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public void close() throws RemotingException { delegate.close(); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public void closeImmediate() throws RemotingException { delegate.closeImmediate(); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public void addCloseHandler(final CloseHandler<Session> closeHandler) { delegate.addCloseHandler(new CloseHandler<Session>() { public void handleClose(final Session closed) { @@ -32,18 +46,30 @@ }); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public ConcurrentMap<Object, Object> getAttributes() { return delegate.getAttributes(); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public String getLocalEndpointName() { return delegate.getLocalEndpointName(); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public String getRemoteEndpointName() { return delegate.getRemoteEndpointName(); } + /** + * {@inheritDoc} This implementation calls the same method on the delegate object. + */ public <I, O> Client<I, O> getRootClient() { return delegate.getRootClient(); } Added: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/package-info.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/package-info.java (rev 0) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/spi/wrapper/package-info.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -0,0 +1,4 @@ +/** + * Wrapper classes for various API elements. + */ +package org.jboss.cx.remoting.spi.wrapper; Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/ObjectSink.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/ObjectSink.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/ObjectSink.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -5,9 +5,18 @@ import java.io.Flushable; /** + * A streaming sink for objects. * + * @param <T> the object type */ public interface ObjectSink<T> extends Flushable, Closeable { + + /** + * Accept an object. + * + * @param instance the object to accept + * @throws IOException if an error occurs + */ void accept(T instance) throws IOException; /** @@ -17,5 +26,10 @@ */ void flush() throws IOException; + /** + * Close the sink. + * + * @throws IOException if an error occurs + */ void close() throws IOException; } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/ObjectSinkWrapper.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/ObjectSinkWrapper.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/ObjectSinkWrapper.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -6,23 +6,12 @@ * */ public class ObjectSinkWrapper<T> implements ObjectSink<T> { - private ObjectSink<T> target; + private final ObjectSink<T> target; - protected ObjectSinkWrapper() { - } - public ObjectSinkWrapper(final ObjectSink<T> target) { this.target = target; } - protected final ObjectSink<T> getTarget() { - return target; - } - - protected final void setTarget(final ObjectSink<T> target) { - this.target = target; - } - public void accept(final T instance) throws IOException { target.accept(instance); } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/ObjectSource.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/ObjectSource.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/ObjectSource.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -5,6 +5,8 @@ /** * A streaming source for objects. + * + * @param <T> the object type */ public interface ObjectSource<T> extends Closeable { Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/ObjectSourceWrapper.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/ObjectSourceWrapper.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/ObjectSourceWrapper.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -6,23 +6,12 @@ * */ public class ObjectSourceWrapper<T> implements ObjectSource<T> { - private ObjectSource<T> target; + private final ObjectSource<T> target; - protected ObjectSourceWrapper() { - } - public ObjectSourceWrapper(final ObjectSource<T> target) { this.target = target; } - protected ObjectSource<T> getTarget() { - return target; - } - - protected void setTarget(final ObjectSource<T> target) { - this.target = target; - } - public boolean hasNext() throws IOException { return target.hasNext(); } Modified: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/Streams.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/Streams.java 2008-06-28 01:39:06 UTC (rev 4333) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/Streams.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -8,20 +8,41 @@ import java.util.NoSuchElementException; /** - * + * Handy utility methods for stream types. */ public final class Streams { private Streams() { } + /** + * Get an object sink that appends to a collection. + * + * @param <T> the collection object type + * @param target the target collection + * @return an object sink + */ public static <T> ObjectSink<T> getCollectionObjectSink(Collection<T> target) { return new CollectionObjectSink<T>(target); } + /** + * Get an object source that reads from an iterator. + * + * @param <T> the iterator object type + * @param iterator the iterater to read from + * @return an object source + */ public static <T> ObjectSource<T> getIteratorObjectSource(Iterator<T> iterator) { return new IteratorObjectSource<T>(iterator); } + /** + * Get an object source that reads from an enumeration. + * + * @param <T> the enumeration object type + * @param enumeration the enumeration to read from + * @return an object source + */ public static <T> ObjectSource<T> getEnumerationObjectSource(Enumeration<T> enumeration) { return new EnumerationObjectSource<T>(enumeration); } Added: remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/package-info.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/package-info.java (rev 0) +++ remoting3/trunk/api/src/main/java/org/jboss/cx/remoting/stream/package-info.java 2008-07-01 03:07:01 UTC (rev 4334) @@ -0,0 +1,4 @@ +/** + * Stream-related API classes. + */ +package org.jboss.cx.remoting.spi.stream;