org.jboss.remoting3
Interface Endpoint

All Superinterfaces:

Attachable, Closeable, HandleableCloseable<Endpoint>

public interface Endpoint
extends HandleableCloseable<Endpoint>, Attachable

A potential participant in a JBoss Remoting communications relationship.

This interface is part of the Remoting public API. It is intended to be consumed by Remoting applications; it is not intended to be implemented by them. Methods may be added to this interface in future minor releases without advance notice.

Nested Class Summary

static class	Endpoint.ListenerFlag Flags which can be passed in to listener registration methods.
static interface	Endpoint.ServiceBuilder<I,O> A service builder for new service registration.

Nested classes/interfaces inherited from interface org.jboss.remoting3.HandleableCloseable

HandleableCloseable.Key

Method Summary

ConnectionProviderRegistration	addConnectionProvider(String uriScheme, ConnectionProviderFactory providerFactory) Register a connection provider for a URI scheme.
<T> Registration	addProtocolService(ProtocolServiceType<T> type, String name, T provider) Register a protocol service.
Registration	addServiceRegistrationListener(ServiceRegistrationListener listener, Set<Endpoint.ListenerFlag> flags) Add a service registration listener which is called whenever a local service is registered.
org.jboss.xnio.IoFuture<? extends Connection>	connect(URI destination, org.jboss.xnio.OptionMap connectOptions) Open a connection with a peer.
org.jboss.xnio.IoFuture<? extends Connection>	connect(URI destination, org.jboss.xnio.OptionMap connectOptions, CallbackHandler callbackHandler) Open a connection with a peer.
org.jboss.xnio.IoFuture<? extends Connection>	connect(URI destination, org.jboss.xnio.OptionMap connectOptions, String userName, String realmName, char[] password) Open a connection with a peer.
<I,O> Client<I,O>	createClient(RequestHandler handler, Class<I> requestClass, Class<O> replyClass) Create a client that uses the given request handler to handle its requests.
<I,O> RequestHandler	createLocalRequestHandler(RequestListener<? super I,? extends O> requestListener, Class<I> requestClass, Class<O> replyClass) Create a request handler that can be used to receive incoming requests on this endpoint.
<T> T	getConnectionProviderInterface(String uriScheme, Class<T> expectedType) Get the interface for a connection provider.
String	getName() Get the name of this endpoint.
Endpoint.ServiceBuilder<?,?>	serviceBuilder() Get a new service builder which can be used to register a service.
<I,O> Endpoint.ServiceBuilder<I,O>	serviceBuilder(Class<I> requestClass, Class<O> replyClass) Get a new service builder which can be used to register a service.

Methods inherited from interface org.jboss.remoting3.HandleableCloseable

addCloseHandler, awaitClosed, awaitClosedUninterruptibly, close

Methods inherited from interface org.jboss.remoting3.Attachable

getAttachments

Method Detail

getName

String getName()

Get the name of this endpoint.

Returns:

the endpoint name, or null if there is no name

serviceBuilder

Endpoint.ServiceBuilder<?,?> serviceBuilder()

Get a new service builder which can be used to register a service.

Returns:

a new service builder

serviceBuilder

<I,O> Endpoint.ServiceBuilder<I,O> serviceBuilder(Class<I> requestClass,
                                                  Class<O> replyClass)

Get a new service builder which can be used to register a service.

Type Parameters:

I - the request type

O - the reply type

Parameters:

requestClass - the request class

replyClass - the reply class

Returns:

a new service builder

addServiceRegistrationListener

Registration addServiceRegistrationListener(ServiceRegistrationListener listener,
                                            Set<Endpoint.ListenerFlag> flags)

Add a service registration listener which is called whenever a local service is registered.

You must have the addServiceListener EndpointPermission to invoke this method.

Parameters:

listener - the listener

flags - the flags to apply to the listener

Returns:

a handle which may be used to remove the listener registration

createLocalRequestHandler

<I,O> RequestHandler createLocalRequestHandler(RequestListener<? super I,? extends O> requestListener,
                                               Class<I> requestClass,
                                               Class<O> replyClass)
                                         throws IOException

Create a request handler that can be used to receive incoming requests 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.

You must have the createRequestHandler EndpointPermission to invoke this method.

Type Parameters:

I - the request type

O - the reply type

Parameters:

requestListener - the request listener

requestClass - the class of requests sent to this request listener

replyClass - the class of replies received back from this request listener

Returns:

the request handler

Throws:

IOException - if an error occurs

createClient

<I,O> Client<I,O> createClient(RequestHandler handler,
                               Class<I> requestClass,
                               Class<O> replyClass)
                         throws IOException

Create a client that uses the given request handler to handle its requests.

You must have the createClient EndpointPermission to invoke this method.

Type Parameters:

I - the request type

O - the reply type

Parameters:

handler - the request handler

requestClass - the class of requests sent through this client

replyClass - the class of replies received back through this client

Returns:

the client

Throws:

IOException - if an error occurs

connect

org.jboss.xnio.IoFuture<? extends Connection> connect(URI destination,
                                                      org.jboss.xnio.OptionMap connectOptions)
                                                      throws IOException

Open a connection with a peer. Returns a future connection which may be used to cancel the connection attempt. This method does not block; use the return value to wait for a result if you wish to block.

You must have the connect EndpointPermission to invoke this method.

Parameters:

destination - the destination

connectOptions - options to configure this connection

Returns:

the future connection

Throws:

IOException - if an error occurs while starting the connect attempt

connect

org.jboss.xnio.IoFuture<? extends Connection> connect(URI destination,
                                                      org.jboss.xnio.OptionMap connectOptions,
                                                      CallbackHandler callbackHandler)
                                                      throws IOException

Open a connection with a peer. Returns a future connection which may be used to cancel the connection attempt. The given callback handler is used to retrieve local authentication information, if the protocol demands it. This method does not block; use the return value to wait for a result if you wish to block.

You must have the connect EndpointPermission to invoke this method.

Parameters:

destination - the destination

connectOptions - options to configure this connection

callbackHandler - the local callback handler to use for authentication

Returns:

the future connection

Throws:

IOException - if an error occurs while starting the connect attempt

connect

org.jboss.xnio.IoFuture<? extends Connection> connect(URI destination,
                                                      org.jboss.xnio.OptionMap connectOptions,
                                                      String userName,
                                                      String realmName,
                                                      char[] password)
                                                      throws IOException

Open a connection with a peer. Returns a future connection which may be used to cancel the connection attempt. The given user name and password is used as local authentication information, if the protocol demands it. This method does not block; use the return value to wait for a result if you wish to block.

You must have the connect EndpointPermission to invoke this method.

Parameters:

destination - the destination

connectOptions - options to configure this connection

userName - the user name to authenticate as, or null if it is unspecified

realmName - the user realm to authenticate with, or null if it is unspecified

password - the password to send, or null if it is unspecified

Returns:

the future connection

Throws:

IOException - if an error occurs while starting the connect attempt

addConnectionProvider

ConnectionProviderRegistration addConnectionProvider(String uriScheme,
                                                     ConnectionProviderFactory providerFactory)
                                                     throws DuplicateRegistrationException

Register a connection provider for a URI scheme. The provider factory is called with the context which can be used to accept new connections or terminate the registration.

You must have the addConnectionProvider EndpointPermission to invoke this method.

Parameters:

uriScheme - the URI scheme

providerFactory - the provider factory

Returns:

a handle which may be used to remove the registration

Throws:

DuplicateRegistrationException - if there is already a provider registered to that URI scheme

getConnectionProviderInterface

<T> T getConnectionProviderInterface(String uriScheme,
                                     Class<T> expectedType)
                                 throws UnknownURISchemeException,
                                        ClassCastException

Get the interface for a connection provider.

You must have the getConnectionProviderInterface EndpointPermission to invoke this method.

Type Parameters:

T - the expected type of the interface

Parameters:

uriScheme - the URI scheme of the registered connection provider

expectedType - the expected type of the interface

Returns:

the provider interface

Throws:

UnknownURISchemeException - if the given URI scheme is not registered

ClassCastException - if the interface type does not match the expected type

addProtocolService

<T> Registration addProtocolService(ProtocolServiceType<T> type,
                                    String name,
                                    T provider)
                                throws DuplicateRegistrationException

Register a protocol service.

Type Parameters:

T - the provider type

Parameters:

type - the type of service being registered

name - the name of the protocol provider

provider - the provider instance

Returns:

a handle which may be used to remove the registration

Throws:

DuplicateRegistrationException - if there is already a protocol registered to that name