org.jboss.remoting3.Endpoint Maven / Gradle / Ivy
/*
* JBoss, Home of Professional Open Source.
* Copyright 2017 Red Hat, Inc., and individual contributors
* as indicated by the @author tags.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.jboss.remoting3;
import static java.security.AccessController.doPrivileged;
import static org.jboss.remoting3.EndpointImpl.AUTH_CONFIGURATION_CLIENT;
import java.io.IOException;
import java.net.InetSocketAddress;
import java.net.URI;
import java.security.GeneralSecurityException;
import java.security.PrivilegedAction;
import org.jboss.remoting3._private.Messages;
import org.jboss.remoting3.security.RemotingPermission;
import org.jboss.remoting3.spi.ConnectionProviderFactory;
import org.wildfly.common.Assert;
import org.wildfly.common.context.ContextManager;
import org.wildfly.common.context.Contextual;
import org.wildfly.security.auth.client.AuthenticationConfiguration;
import org.wildfly.security.auth.client.AuthenticationContext;
import org.wildfly.security.auth.client.AuthenticationContextConfigurationClient;
import org.xnio.FailedIoFuture;
import org.xnio.IoFuture;
import org.xnio.OptionMap;
import org.xnio.XnioWorker;
import javax.net.ssl.SSLContext;
import javax.security.auth.callback.CallbackHandler;
/**
* 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.
*
* @apiviz.landmark
*/
public interface Endpoint extends HandleableCloseable, Attachable, Contextual {
/**
* The context manager for Remoting endpoints.
*/
ContextManager ENDPOINT_CONTEXT_MANAGER = doPrivileged((PrivilegedAction>) () -> {
final ContextManager contextManager = new ContextManager<>(Endpoint.class, "jboss-remoting.endpoint");
contextManager.setGlobalDefaultSupplierIfNotSet(ConfigurationEndpointSupplier::new);
return contextManager;
});
/**
* Get the context manager for Remoting endpoints ({@link #ENDPOINT_CONTEXT_MANAGER}).
*
* @return the context manager for Remoting endpoints (not {@code null})
*/
default ContextManager getInstanceContextManager() {
return EndpointImpl.ENDPOINT_CONTEXT_MANAGER;
}
/**
* Get the currently active Remoting endpoint. If none is selected, {@code null} is returned.
*
* @return the currently active Remoting endpoint, or {@code null} if none
*/
static Endpoint getCurrent() {
return EndpointGetterHolder.SUPPLIER.get();
}
/**
* Get the name of this endpoint.
*
* @return the endpoint name, or {@code null} if there is no name
*/
String getName();
/**
* Register a new service.
*
* @param serviceType the service type
* @param openListener the channel open listener
* @param optionMap the option map
* @return the service registration which may be closed to remove the service
* @throws ServiceRegistrationException if the service could not be registered
*/
Registration registerService(String serviceType, OpenListener openListener, OptionMap optionMap) throws ServiceRegistrationException;
/**
* Get a possibly shared, possibly existing connection to the destination. The authentication and SSL configuration is selected from
* the given context with the given abstract type (if specified).
*
* @param destination the destination URI (must not be {@code null})
* @param abstractType the abstract type of the connection (may be {@code null})
* @param abstractTypeAuthority the authority name of the abstract type of the connection (may be {@code null})
* @param context the authentication context to use (must not be {@code null})
* @return the future connection identity (not {@code null})
*/
default IoFuture getConnectedIdentity(URI destination, String abstractType, String abstractTypeAuthority, AuthenticationContext context) {
Assert.checkNotNullParam("destination", destination);
Assert.checkNotNullParam("context", context);
final AuthenticationContextConfigurationClient client = AUTH_CONFIGURATION_CLIENT;
final SSLContext sslContext;
try {
sslContext = client.getSSLContext(destination, context);
} catch (GeneralSecurityException e) {
return new FailedIoFuture<>(Messages.conn.failedToConfigureSslContext(e));
}
final AuthenticationConfiguration authenticationConfiguration = client.getAuthenticationConfiguration(destination, context, -1, abstractType, abstractTypeAuthority);
return getConnectedIdentity(destination, sslContext, authenticationConfiguration);
}
/**
* Get a possibly shared, possibly existing connection to the destination. The authentication and SSL configuration is selected from
* the currently active authentication context with the given abstract type (if specified).
*
* @param destination the destination URI (must not be {@code null})
* @param abstractType the abstract type of the connection (may be {@code null})
* @param abstractTypeAuthority the authority name of the abstract type of the connection (may be {@code null})
* @return the future connection identity (not {@code null})
*/
default IoFuture getConnectedIdentity(URI destination, String abstractType, String abstractTypeAuthority) {
return getConnectedIdentity(destination, abstractType, abstractTypeAuthority, AuthenticationContext.captureCurrent());
}
/**
* Get a possibly shared, possibly existing connection to the destination. The authentication and SSL configuration is specified
* directly.
*
* @param destination the destination URI (must not be {@code null})
* @param sslContext the SSL context to use for secure connections (may be {@code null})
* @param authenticationConfiguration the authentication configuration to use (must not be {@code null})
* @return the future connection identity (not {@code null})
*/
IoFuture getConnectedIdentity(URI destination, SSLContext sslContext, AuthenticationConfiguration authenticationConfiguration);
/**
* Get a possibly shared, possibly existing connection to the destination, if the connection was already established.
* The authentication and SSL configuration is specified directly.
*
* If no existing connection was found, {@code null} is returned. If a non-{@code null} {@code IoFuture} is
* returned, it may represent a complete connection, a failed attempt, or an in-progress attempt.
*
* @param destination the destination URI (must not be {@code null})
* @param abstractType the abstract type of the connection (may be {@code null})
* @param abstractTypeAuthority the authority name of the abstract type of the connection (may be {@code null})
* @param context the authentication context to use (must not be {@code null})
* @return the existing connection, or {@code null} if no connection currently exists
*/
default IoFuture getConnectedIdentityIfExists(URI destination, String abstractType, String abstractTypeAuthority, AuthenticationContext context) {
Assert.checkNotNullParam("destination", destination);
Assert.checkNotNullParam("context", context);
final AuthenticationContextConfigurationClient client = AUTH_CONFIGURATION_CLIENT;
final SSLContext sslContext;
try {
sslContext = client.getSSLContext(destination, context);
} catch (GeneralSecurityException e) {
return new FailedIoFuture<>(Messages.conn.failedToConfigureSslContext(e));
}
final AuthenticationConfiguration authenticationConfiguration = client.getAuthenticationConfiguration(destination, context, -1, abstractType, abstractTypeAuthority);
return getConnectedIdentityIfExists(destination, sslContext, authenticationConfiguration);
}
/**
* Get a possibly shared, possibly existing connection to the destination, if the connection was already established.
* The authentication and SSL configuration is specified directly.
*
* If no existing connection was found, {@code null} is returned. If a non-{@code null} {@code IoFuture} is
* returned, it may represent a complete connection, a failed attempt, or an in-progress attempt.
*
* @param destination the destination URI (must not be {@code null})
* @param sslContext the SSL context to use for secure connections (may be {@code null})
* @param authenticationConfiguration the authentication configuration to use (must not be {@code null})
* @return the existing connection, or {@code null} if no connection currently exists
*/
IoFuture getConnectedIdentityIfExists(URI destination, SSLContext sslContext, AuthenticationConfiguration authenticationConfiguration);
/**
* Get a possibly pre-existing connection to the destination.
*
* @param destination the destination URI
* @return the future (or existing) connection
*/
@Deprecated
default IoFuture getConnection(URI destination) {
return getConnection(destination, (String) null, null);
}
/**
* Get a possibly pre-existing connection to the destination. The given abstract type and authority are used
* to locate the authentication configuration.
*
* @param destination the destination URI (must not be {@code null})
* @param abstractType the abstract type of the connection (may be {@code null})
* @param abstractTypeAuthority the authority name of the abstract type of the connection (may be {@code null})
* @return the future (or existing) connection
*/
@Deprecated
default IoFuture getConnection(URI destination, String abstractType, String abstractTypeAuthority) {
return new ToConnectionFuture(getConnectedIdentity(destination, abstractType, abstractTypeAuthority));
}
/**
* Get a possibly pre-existing connection to the destination. The given authentication configuration is used to
* authenticate the connection.
*
* The given SSL context factory is used only for TLS-based protocols. It may be {@code null}, but in such cases,
* no TLS-based protocols will be available.
*
* @param destination the destination URI (must not be {@code null})
* @param sslContext the SSL context to use for secure connections (may be {@code null})
* @param authenticationConfiguration the authentication configuration to use (must not be {@code null})
* @return the future (or existing) connection
*/
@Deprecated
default IoFuture getConnection(URI destination, SSLContext sslContext, AuthenticationConfiguration authenticationConfiguration) {
return new ToConnectionFuture(getConnectedIdentity(destination, sslContext, authenticationConfiguration));
}
/**
* Get a possibly pre-existing connection to the destination. The connection authentication configuration is used
* to authenticate
* the peer if the connection supports multiple identity switching. The run authentication configuration is used to
* authenticate
* the peer if the connection does not support multiple identity switching.
*
* @param destination the destination URI (must not be {@code null})
* @param sslContext the SSL context to use for secure connections (may be {@code null})
* @param connectionConfiguration the connection authentication configuration (must not be {@code null})
* @param operateConfiguration the run authentication configuration (must not be {@code null})
* @return the future (or existing) connection
*/
@Deprecated
default IoFuture getConnection(URI destination, SSLContext sslContext, AuthenticationConfiguration connectionConfiguration, AuthenticationConfiguration operateConfiguration) {
return getConnection(destination, sslContext, operateConfiguration);
}
/**
* Get a pre-existing connection to the destination. The connection authentication configuration is used to
* authenticate
* the peer if the connection supports multiple identity switching. The run authentication configuration is used to
* authenticate
* the peer if the connection does not support multiple identity switching.
*
* If no existing connection was found, {@code null} is returned. If a non-{@code null} {@code IoFuture} is
* returned, it may represent a complete connection, a failed attempt, or an in-progress attempt.
*
* @param destination the destination URI (must not be {@code null})
* @param sslContext the SSL context to use for secure connections (may be {@code null})
* @param connectionConfiguration the connection authentication configuration (must not be {@code null})
* @param operateConfiguration the run authentication configuration (must not be {@code null})
* @return the existing connection, or {@code null} if no connection currently exists
*/
@Deprecated
default IoFuture getConnectionIfExists(URI destination, SSLContext sslContext, AuthenticationConfiguration connectionConfiguration, AuthenticationConfiguration operateConfiguration) {
return new ToConnectionFuture(getConnectedIdentityIfExists(destination, sslContext, operateConfiguration));
}
/**
* Get a pre-existing connection to the destination.
*
* If no existing connection was found, {@code null} is returned. If a non-{@code null} {@code IoFuture} is
* returned, it may represent a complete connection, a failed attempt, or an in-progress attempt.
*
* @param destination the destination URI (must not be {@code null})
* @param abstractType the abstract type of the connection (may be {@code null})
* @param abstractTypeAuthority the authority name of the abstract type of the connection (may be {@code null})
* @return the existing connection, or {@code null} if no connection currently exists
*/
@Deprecated
default IoFuture getConnectionIfExists(URI destination, String abstractType, String abstractTypeAuthority) {
final AuthenticationContext context = AuthenticationContext.captureCurrent();
final AuthenticationContextConfigurationClient client = AUTH_CONFIGURATION_CLIENT;
final SSLContext sslContext;
try {
sslContext = client.getSSLContext(destination, context);
} catch (GeneralSecurityException e) {
return new FailedIoFuture<>(Messages.conn.failedToConfigureSslContext(e));
}
final AuthenticationConfiguration authenticationConfiguration = client.getAuthenticationConfiguration(destination, context, -1, abstractType, abstractTypeAuthority);
return getConnectionIfExists(destination, sslContext, authenticationConfiguration, authenticationConfiguration);
}
/**
* Get a pre-existing shared connection to the destination.
*
* If no existing connection was found, {@code null} is returned. If a non-{@code null} {@code IoFuture} is
* returned, it may represent a complete connection, a failed attempt, or an in-progress attempt.
*
* @param destination the destination URI (must not be {@code null})
* @return the existing connection, or {@code null} if no connection currently exists
*/
@Deprecated
default IoFuture getConnectionIfExists(URI destination) {
return getConnectionIfExists(destination, null, null);
}
/**
* Open an unshared 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 {@link RemotingPermission connect EndpointPermission} to invoke this method.
*
* @param destination the destination
*
* @return the future connection
*/
default IoFuture connect(URI destination) {
return connect(destination, OptionMap.EMPTY);
}
/**
* Open an unshared 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 {@link RemotingPermission connect EndpointPermission} to invoke this method.
*
* @param destination the destination
* @param connectOptions options to configure this connection
*
* @return the future connection
*/
IoFuture connect(URI destination, OptionMap connectOptions);
/**
* Open an unshared 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 {@link RemotingPermission connect EndpointPermission} to invoke this method.
*
* @param destination the destination
* @param connectOptions options to configure this connection
* @param authenticationContext the client authentication context to use
*
* @return the future connection
*/
IoFuture connect(URI destination, OptionMap connectOptions, AuthenticationContext authenticationContext);
/**
* Open an unshared 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 {@link RemotingPermission connect EndpointPermission} to invoke this method.
*
* @param destination the destination
* @param bindAddress the local bind address
* @param connectOptions options to configure this connection
* @param authenticationContext the client authentication context to use
*
* @return the future connection
*/
IoFuture connect(URI destination, InetSocketAddress bindAddress, OptionMap connectOptions, AuthenticationContext authenticationContext);
/**
* Open an unshared 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 {@link RemotingPermission connect EndpointPermission} to invoke this method.
*
* @param destination the destination
* @param bindAddress the local bind address
* @param connectOptions options to configure this connection
* @param sslContext the SSL context to use for secure connections (may be {@code null})
* @param connectionConfiguration the connection authentication configuration (must not be {@code null})
* @return the future connection (not {@code null})
*/
IoFuture connect(URI destination, InetSocketAddress bindAddress, OptionMap connectOptions, SSLContext sslContext, AuthenticationConfiguration connectionConfiguration);
/**
* Open an unshared 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 {@link RemotingPermission connect EndpointPermission} to invoke this method.
*
* @param destination the destination
* @param connectOptions options to configure this connection
* @param callbackHandler the local callback handler to use for authentication
* @return the future connection (not {@code null})
*/
@Deprecated
IoFuture connect(URI destination, OptionMap connectOptions, CallbackHandler callbackHandler) throws IOException;
/**
* 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 {@link RemotingPermission addConnectionProvider EndpointPermission} to invoke this method.
*
* @param uriScheme the URI scheme
* @param providerFactory the provider factory
* @param optionMap the configuration options for the connection provider
* @return a handle which may be used to remove the registration
* @throws IOException if the provider failed to initialize
* @throws DuplicateRegistrationException if there is already a provider registered to that URI scheme
*/
Registration addConnectionProvider(String uriScheme, ConnectionProviderFactory providerFactory, OptionMap optionMap) throws DuplicateRegistrationException, IOException;
/**
* Get the interface for a connection provider.
*
* You must have the {@link RemotingPermission getConnectionProviderInterface EndpointPermission} to invoke this method.
*
* @param uriScheme the URI scheme of the registered connection provider
* @param expectedType the expected type of the interface
* @param the expected type of the interface
* @return the provider interface
* @throws UnknownURISchemeException if the given URI scheme is not registered
* @throws ClassCastException if the interface type does not match the expected type
*/
T getConnectionProviderInterface(String uriScheme, Class expectedType) throws UnknownURISchemeException, ClassCastException;
/**
* Determine whether the given URI scheme is valid for this endpoint.
*
* @param uriScheme the URI scheme
* @return {@code true} if the URI scheme is valid at the time this method is called
*/
boolean isValidUriScheme(String uriScheme);
/**
* Get the XNIO worker configured for this endpoint.
*
* @return the XNIO worker
*/
XnioWorker getXnioWorker();
/**
* Create a new endpoint builder.
*
* @return the new endpoint builder
*/
static EndpointBuilder builder() {
return new EndpointBuilder();
}
}