[jboss-remoting-commits] JBoss Remoting SVN: r4714 - in remoting3/trunk/api/src/main/java/org/jboss/remoting: spi and 1 other directory.

Author: david.lloyd(a)jboss.com Date: 2008-11-19 20:07:52 -0500 (Wed, 19 Nov 2008) New Revision: 4714 Modified: remoting3/trunk/api/src/main/java/org/jboss/remoting/LocalServiceConfiguration.java remoting3/trunk/api/src/main/java/org/jboss/remoting/RemoteServiceConfiguration.java remoting3/trunk/api/src/main/java/org/jboss/remoting/ServiceListener.java remoting3/trunk/api/src/main/java/org/jboss/remoting/ServiceRegistrationException.java remoting3/trunk/api/src/main/java/org/jboss/remoting/spi/AutoCloseable.java remoting3/trunk/api/src/main/java/org/jboss/remoting/spi/Handle.java remoting3/trunk/api/src/main/java/org/jboss/remoting/spi/RequestHandler.java remoting3/trunk/api/src/main/java/org/jboss/remoting/spi/SpiUtils.java Log: Javadoc updates Modified: remoting3/trunk/api/src/main/java/org/jboss/remoting/LocalServiceConfiguration.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/remoting/LocalServiceConfiguration.java 2008-11-19 20:24:40 UTC (rev 4713) +++ remoting3/trunk/api/src/main/java/org/jboss/remoting/LocalServiceConfiguration.java 2008-11-20 01:07:52 UTC (rev 4714) @@ -33,44 +33,96 @@ private String groupName; private int metric; + /** + * Construct a new instance. + * + * @param requestListener the request listener + * @param requestClass the request class + * @param replyClass the reply class + */ public LocalServiceConfiguration(final RequestListener<I, O> requestListener, final Class<I> requestClass, final Class<O> replyClass) { this.requestListener = requestListener; this.requestClass = requestClass; this.replyClass = replyClass; } + /** + * Get the request listener for this service. + * + * @return the request listener + */ public RequestListener<I, O> getRequestListener() { return requestListener; } + /** + * Get the request class. + * + * @return the request class + */ public Class<I> getRequestClass() { return requestClass; } + /** + * Get the reply class. + * + * @return the reply class + */ public Class<O> getReplyClass() { return replyClass; } + /** + * Get the service type. + * + * @return the service type + */ public String getServiceType() { return serviceType; } + /** + * Set the service type. + * + * @param serviceType the service type + */ public void setServiceType(final String serviceType) { this.serviceType = serviceType; } + /** + * Get the group name. + * + * @return the group name + */ public String getGroupName() { return groupName; } + /** + * Set the group name. + * + * @param groupName the group name + */ public void setGroupName(final String groupName) { this.groupName = groupName; } + /** + * Get the metric. + * + * @return the metric + */ public int getMetric() { return metric; } + /** + * Set the metric. + * + * @param metric the metric + */ public void setMetric(final int metric) { this.metric = metric; } Modified: remoting3/trunk/api/src/main/java/org/jboss/remoting/RemoteServiceConfiguration.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/remoting/RemoteServiceConfiguration.java 2008-11-19 20:24:40 UTC (rev 4713) +++ remoting3/trunk/api/src/main/java/org/jboss/remoting/RemoteServiceConfiguration.java 2008-11-20 01:07:52 UTC (rev 4714) @@ -25,7 +25,7 @@ import org.jboss.remoting.spi.RequestHandlerSource; /** - * + * A configuration for registering a remote service with an endpoint. */ public final class RemoteServiceConfiguration { private String serviceType; @@ -34,42 +34,98 @@ private RequestHandlerSource requestHandlerSource; private int metric; + /** + * Construct a new instance. + */ + public RemoteServiceConfiguration() { + } + + /** + * Get the service type. + * + * @return the service type + */ public String getServiceType() { return serviceType; } + /** + * Set the service type. + * + * @param serviceType the service type + */ public void setServiceType(final String serviceType) { this.serviceType = serviceType; } + /** + * Get the service group name. + * + * @return the group name + */ public String getGroupName() { return groupName; } + /** + * Set the service group name. + * + * @param groupName the group name + */ public void setGroupName(final String groupName) { this.groupName = groupName; } + /** + * Get the remote endpoint name. + * + * @return the remote endpoint name + */ public String getEndpointName() { return endpointName; } + /** + * Set the remote endpoint name. + * + * @param endpointName the remote endpoint name + */ public void setEndpointName(final String endpointName) { this.endpointName = endpointName; } + /** + * Get the request handler source of the remote service. + * + * @return the request handler source + */ public RequestHandlerSource getRequestHandlerSource() { return requestHandlerSource; } + /** + * Set the request handler source of the remote service. + * + * @param requestHandlerSource the request handler source + */ public void setRequestHandlerSource(final RequestHandlerSource requestHandlerSource) { this.requestHandlerSource = requestHandlerSource; } + /** + * Get the metric of the remote service. + * + * @return the metric + */ public int getMetric() { return metric; } + /** + * Set the metric of the remote service. + * + * @param metric the metric + */ public void setMetric(final int metric) { this.metric = metric; } Modified: remoting3/trunk/api/src/main/java/org/jboss/remoting/ServiceListener.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/remoting/ServiceListener.java 2008-11-19 20:24:40 UTC (rev 4713) +++ remoting3/trunk/api/src/main/java/org/jboss/remoting/ServiceListener.java 2008-11-20 01:07:52 UTC (rev 4714) @@ -38,7 +38,7 @@ void serviceRegistered(SimpleCloseable listenerHandle, ServiceInfo info); /** - * + * Information about a registered service. */ final class ServiceInfo { private String endpointName; @@ -49,58 +49,134 @@ private RequestHandlerSource requestHandlerSource; private SimpleCloseable registrationHandle; + /** + * Construct a new instance. + */ + public ServiceInfo() { + } + + /** + * Get the service type. + * + * @return the service type + */ public String getServiceType() { return serviceType; } + /** + * Set the service type. + * + * @param serviceType the service type + */ public void setServiceType(final String serviceType) { this.serviceType = serviceType; } + /** + * Get the group name. + * + * @return the group name + */ public String getGroupName() { return groupName; } + /** + * Set the group name. + * + * @param groupName the group name + */ public void setGroupName(final String groupName) { this.groupName = groupName; } + /** + * Get the metric. + * + * @return the metric + */ public int getMetric() { return metric; } + /** + * Set the metric. + * + * @param metric the metric + */ public void setMetric(final int metric) { this.metric = metric; } + /** + * Get the request handler source. + * + * @return the request handler source + */ public RequestHandlerSource getRequestHandlerSource() { return requestHandlerSource; } + /** + * Set the request handler source. + * + * @param requestHandlerSource the request handler source + */ public void setRequestHandlerSource(final RequestHandlerSource requestHandlerSource) { this.requestHandlerSource = requestHandlerSource; } + /** + * Get the registration handle. Closing this handle will remove the registration. + * + * @return the registration handle + */ public SimpleCloseable getRegistrationHandle() { return registrationHandle; } + /** + * Set the registration handle. + * + * @param registrationHandle the registration handle + */ public void setRegistrationHandle(final SimpleCloseable registrationHandle) { this.registrationHandle = registrationHandle; } + /** + * Get the endpoint name. For local services, this will be the name of the local endpoint. + * + * @return the endpoint name + */ public String getEndpointName() { return endpointName; } + /** + * Set the endpoint name. + * + * @param endpointName the endpoint name + */ public void setEndpointName(final String endpointName) { this.endpointName = endpointName; } + /** + * Determine whether this service is remote. + * + * @return {@code true} if this service is remote + */ public boolean isRemote() { return remote; } + /** + * Specify whether this service is remote. + * + * @param remote {@code true} if this service is remote + */ public void setRemote(final boolean remote) { this.remote = remote; } Modified: remoting3/trunk/api/src/main/java/org/jboss/remoting/ServiceRegistrationException.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/remoting/ServiceRegistrationException.java 2008-11-19 20:24:40 UTC (rev 4713) +++ remoting3/trunk/api/src/main/java/org/jboss/remoting/ServiceRegistrationException.java 2008-11-20 01:07:52 UTC (rev 4714) @@ -22,10 +22,8 @@ package org.jboss.remoting; -import org.jboss.remoting.RemotingException; - /** - * + * A service registration exception, thrown when registering a service fails for some reason. */ public class ServiceRegistrationException extends RemotingException { Modified: remoting3/trunk/api/src/main/java/org/jboss/remoting/spi/AutoCloseable.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/remoting/spi/AutoCloseable.java 2008-11-19 20:24:40 UTC (rev 4713) +++ remoting3/trunk/api/src/main/java/org/jboss/remoting/spi/AutoCloseable.java 2008-11-20 01:07:52 UTC (rev 4714) @@ -26,8 +26,16 @@ import java.io.IOException; /** - * + * A closeable resource which closes automatically when the number of active handles reaches zero. Handles are considered + * active until they are closed. */ public interface AutoCloseable<T> extends HandleableCloseable<T> { + + /** + * Get a handle to this resource. When the number of open handles reaches zero, the resource will be closed. + * + * @return a handle + * @throws IOException if an error occurs, particularly if this resource is already closed + */ Handle<T> getHandle() throws IOException; } Modified: remoting3/trunk/api/src/main/java/org/jboss/remoting/spi/Handle.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/remoting/spi/Handle.java 2008-11-19 20:24:40 UTC (rev 4713) +++ remoting3/trunk/api/src/main/java/org/jboss/remoting/spi/Handle.java 2008-11-20 01:07:52 UTC (rev 4714) @@ -27,7 +27,7 @@ import org.jboss.remoting.HandleableCloseable; /** - * A handle to a local resource. + * A handle to a reference-counted {@link org.jboss.remoting.spi.AutoCloseable AutoCloseable} resource. */ public interface Handle<T> extends HandleableCloseable<Handle<T>> { @@ -39,7 +39,8 @@ T getResource(); /** - * Close this reference. + * Close this handle. If this is the last handle to be closed, also close the resource (throwing any exception + * that may result). * * @throws IOException if the close failed */ Modified: remoting3/trunk/api/src/main/java/org/jboss/remoting/spi/RequestHandler.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/remoting/spi/RequestHandler.java 2008-11-19 20:24:40 UTC (rev 4713) +++ remoting3/trunk/api/src/main/java/org/jboss/remoting/spi/RequestHandler.java 2008-11-20 01:07:52 UTC (rev 4714) @@ -28,6 +28,10 @@ /** * A request handler, which can be passed to remote endpoints. Remote systems can then use the handler * to make invocations, or they may forward a handler on to other remote systems. + * <p> + * This is an internal Remoting interface, intended to be implemented only by Remoting internals and protocol implementations. + * It should not be implemented by end-users, as members may be added without notice. Applications should instead use + * the {@link org.jboss.remoting.Client Client} and {@link org.jboss.remoting.RequestListener RequestListener} interfaces. */ public interface RequestHandler extends AutoCloseable<RequestHandler> { Modified: remoting3/trunk/api/src/main/java/org/jboss/remoting/spi/SpiUtils.java =================================================================== --- remoting3/trunk/api/src/main/java/org/jboss/remoting/spi/SpiUtils.java 2008-11-19 20:24:40 UTC (rev 4713) +++ remoting3/trunk/api/src/main/java/org/jboss/remoting/spi/SpiUtils.java 2008-11-20 01:07:52 UTC (rev 4714) @@ -82,6 +82,7 @@ /** * Safely notify a request listener's cancel handler of cancellation. * + * @param <O> the reply type * @param handler the request cancel handler * @param requestContext the request context */ @@ -108,6 +109,11 @@ } } + /** + * Get a remote request context that simply ignores a cancel request. + * + * @return a blank remote request context + */ public static RemoteRequestContext getBlankRemoteRequestContext() { return BLANK_REMOTE_REQUEST_CONTEXT; }