[jboss-cvs] JBossAS SVN: r72580 - trunk/cluster/src/main/org/jboss/ha/framework/server.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Apr 22 12:46:07 EDT 2008
Author: bstansberry at jboss.com
Date: 2008-04-22 12:46:06 -0400 (Tue, 22 Apr 2008)
New Revision: 72580
Modified:
trunk/cluster/src/main/org/jboss/ha/framework/server/JChannelFactory.java
trunk/cluster/src/main/org/jboss/ha/framework/server/JChannelFactoryMBean.java
Log:
[JBAS-5329] Javadoc
Modified: trunk/cluster/src/main/org/jboss/ha/framework/server/JChannelFactory.java
===================================================================
--- trunk/cluster/src/main/org/jboss/ha/framework/server/JChannelFactory.java 2008-04-22 16:35:36 UTC (rev 72579)
+++ trunk/cluster/src/main/org/jboss/ha/framework/server/JChannelFactory.java 2008-04-22 16:46:06 UTC (rev 72580)
@@ -67,8 +67,22 @@
import org.jgroups.util.Util;
/**
- * Extension to the JGroups JChannelFactory that supports the addition
- * of "additional_data" to the channel config.
+ * Extension to the JGroups JChannelFactory that supports a number of
+ * JBoss AS-specific behaviors:
+ * <p>
+ * <ul>
+ * <li>Passing a config event to newly created channels containing
+ * "additional_data" that will be associated with the JGroups
+ * <code>IpAddress</code> for the peer. Used to provide logical addresses
+ * to cluster peers that remain consistent across channel and server restarts.</li>
+ * <li>Never returns instances of {@link org.jgroups.mux.MuxChannel} from
+ * the <code>createMultiplexerChannel</code> methods. Instead always returns
+ * a channel with a shared transport protocol.</li>
+ * <li>Configures the channel's thread pools and thread factories to ensure
+ * that application thread context classloaders don't leak to the channel
+ * threads.</li>
+ * </ul>
+ * </p>
*
* @author <a href="mailto://brian.stansberry@jboss.com">Brian Stansberry</a>
*
@@ -79,7 +93,7 @@
{
protected static Logger log = Logger.getLogger(JChannelFactory.class);
- private static final String UNSHARED_TRANSPORT_NAME_BASE = "unnamed_";
+ public static final String UNSHARED_TRANSPORT_NAME_BASE = "unnamed_";
private static final int CREATED = ServiceMBean.CREATED;
private static final int STARTING = ServiceMBean.STARTING;
@@ -106,13 +120,13 @@
}
+ /**
+ * Always throws <code>ChannelException</code>; this method is not supported.
+ */
@Override
public Channel createChannel() throws ChannelException
{
- // Use type 'Object' so we call createChannel(Object) not createChannel(String)
-// Object stack = JChannel.DEFAULT_PROTOCOL_STACK;
-// return createChannel(stack);
- throw new UnsupportedOperationException("No-arg createChannel() is not supported");
+ throw new ChannelException("No-arg createChannel() is not supported");
}
@Override
@@ -138,15 +152,14 @@
}
/**
- * {@inheritDoc}
+ * Create a {@link Channel} using the specified stack. Channel will use a
+ * shared transport if the <code>singleton-name</code> attribute is
+ * set on the stack's transport protocol.
*
- * Overrides the superclass version by generating a unique node id
- * and passing it down the Channel as additional_data and by suppressing the
- * <code>register_for_state_transfer</code> param.
- * <p/>
- * The additional data is the value of {@link #getNodeName()} which either
- * can be injected as part of configuration or will be calculated
- * the first time a channel is created.
+ * @param stack_name the name of the stack
+ * @return the channel
+ *
+ * @throws Exception
*/
@Override
public Channel createChannel(String stack_name) throws Exception
@@ -179,15 +192,44 @@
}
/**
- * {@inheritDoc}
+ * Creates and returns a shared transport Channel configured with the specified
+ * {@link #getConfig(String) protocol stack configuration}.
+ * <p>
+ * <emphasis>NOTE:</emphasis> The implementation of this method is somewhat
+ * different from what is described in
+ * {@link org.jgroups.ChannelFactory#createMultiplexerChannel(String, String)}.
+ * The returned channel will not be an instance of
+ * <code>org.jgroups.mux.MuxChannel</code>; rather a channel that uses a
+ * shared transport will be returned. This will be the case whether or
+ * not the protocol stack specified by <code>stack_name</code> includes
+ * a <code>singleton_name</code> attribute in its
+ * {@link org.jgroups.protocols.TP transport protocol} configuration. If no
+ * <code>singleton_name</code> attribute is present, this factory will create
+ * a synthetic one by prepending "unnamed_" to the provided
+ * <code>id</code> param and will use that for the returned channel's
+ * transport protocol. (Note this will not effect the protocol stack
+ * configuration named by <code>stack_name</code>; i.e. another request
+ * that passes the same <code>stack_name</code> will not inherit the
+ * synthetic singleton name.)
*
- * Overrides the superclass version by generating a unique node id
- * and passing it down the Channel as additional_data and by suppressing the
- * <code>register_for_state_transfer</code> param.
- * <p/>
- * The additional data is the value of {@link #getNodeName()} which either
- * can be injected as part of configuration or will be calculated
- * the first time a channel is created.
+ * @param stack_name
+ * The name of the stack to be used. All stacks are defined in
+ * the configuration with which the factory is configured (see
+ * {@link #setMultiplexerConfig(Object)} for example. If
+ * clients attempt to create a Channel for an undefined stack
+ * name an Exception will be thrown.
+ * @param id Only used if the transport protocol configuration for the
+ * specified stack does not include the <code>singleton_name</code>
+ * attribute; then it is used to create a synthetic singleton-name
+ * for the channel's protocol stack.
+ *
+ * @return An implementation of Channel configured with a shared transport.
+ *
+ * @throws IllegalStateException if the specified protocol stack does not
+ * declare a <code>singleton_name</code> and
+ * {@link #getAddMissingSingletonName()} returns
+ * <code>false</code>.
+ * @throws ChannelException
*/
@Override
public Channel createMultiplexerChannel(String stack_name, String id) throws Exception
@@ -245,15 +287,24 @@
/**
- * {@inheritDoc}
+ * Creates and returns a shared transport Channel configured with the specified
+ * {@link #getConfig(String) protocol stack configuration}.
*
- * Overrides the superclass version by generating a unique node id
- * and passing it down the Channel as additional_data and by suppressing the
- * <code>register_for_state_transfer</code> param.
- * <p/>
- * The additional data is the value of {@link #getNodeName()} which either
- * can be injected as part of configuration or will be calculated
- * the first time a channel is created.
+ * See {@link #createMultiplexerChannel(String, String)}; the additional
+ * attributes specified in this overloaded version of that method are ignored.
+ *
+ * @param register_for_state_transfer ignored in JBoss AS. Treated as <code>false</code>.
+ *
+ * @param substate_id ignored in JBoss AS
+ *
+ * @return An implementation of Channel configured with a shared transport.
+ *
+ *
+ * @throws IllegalStateException if the specified protocol stack does not
+ * declare a <code>singleton_name</code> and
+ * {@link #getAddMissingSingletonName()} returns
+ * <code>false</code>.
+ * @throws ChannelException
*/
@Override
public Channel createMultiplexerChannel(String stack_name, String id, boolean register_for_state_transfer, String substate_id) throws Exception
@@ -267,35 +318,84 @@
super.setDomain(domain);
domainSet = true;
}
-
- public InetAddress getNodeAddress()
- {
- return nodeAddress;
- }
-
- public void setNodeAddress(InetAddress nodeAddress)
- {
- this.nodeAddress = nodeAddress;
- }
-
-
+ /**
+ * Get any logical name assigned to this server; if not null this value
+ * will be the value of the
+ * {@link #setAssignLogicalAddresses(boolean) logical address} assigned
+ * to the channels this factory creates.
+ *
+ * @return the logical name for this server, or <code>null</code>.
+ */
public String getNodeName()
{
return nodeName;
}
-
+ /**
+ * Sets the logical name assigned to this server; if not null this value
+ * will be the value of the
+ * {@link #setAssignLogicalAddresses(boolean) logical address} assigned
+ * to the channels this factory creates.
+ *
+ * @param nodeName the logical name for this server, or <code>null</code>.
+ */
public void setNodeName(String nodeName)
{
this.nodeName = nodeName;
}
+
+ /**
+ * Gets the address to which this server is bound; typically the value
+ * passed to <code>-b</code> when JBoss is started. Used in combination
+ * with {@link #getNamingServicePort() the naming service port} to create
+ * a logical name for this server if no {@link #SetNodeName(String) node name}
+ * is specified.
+ *
+ * @return the address to which this server is bound, or <code>null</code>
+ * if not set
+ */
+ public InetAddress getNodeAddress()
+ {
+ return nodeAddress;
+ }
+
+ /**
+ * Sets the address to which this server is bound; typically the value
+ * passed to <code>-b</code> when JBoss is started. Used in combination
+ * with {@link #getNamingServicePort() the naming service port} to create
+ * a logical name for this server if no {@link #SetNodeName(String) node name}
+ * is specified.
+ *
+ * @param nodeAddress the address to which this server is bound,
+ * or <code>null</code>
+ */
+ public void setNodeAddress(InetAddress nodeAddress)
+ {
+ this.nodeAddress = nodeAddress;
+ }
+ /**
+ * Gets the port on which this server's naming service is listening. Used in
+ * combination with {@link #getNodeAddress() the server bind address} to create
+ * a logical name for this server if no {@link #SetNodeName(String) node name}
+ * is specified.
+ *
+ * @return the port on which JNDI is listening, or <code>-1</code> if not set.
+ */
public int getNamingServicePort()
{
return namingServicePort;
}
+ /**
+ * Sets the port on which this server's naming service is listening. Used in
+ * combination with {@link #getNodeAddress() the server bind address} to create
+ * a logical name for this server if no {@link #SetNodeName(String) node name}
+ * is specified.
+ *
+ * @param jndiPort the port on which JNDI is listening.
+ */
public void setNamingServicePort(int jndiPort)
{
this.namingServicePort = jndiPort;
@@ -333,21 +433,57 @@
this.assignLogicalAddresses = logicalAddresses;
}
+ /**
+ * Gets whether this factory should override the standard JGroups
+ * thread pools and thread factories to ensure application classloaders do
+ * not leak to channel threads.
+ *
+ * @return <code>true</code> if the pools and factories should be overridden.
+ * Default is <code>true</code>.
+ */
public boolean getManageChannelThreadPools()
{
return manageChannelThreadPools;
}
+ /**
+ * Sets whether this factory should override the standard JGroups
+ * thread pools and thread factories to ensure application classloaders do
+ * not leak to channel threads. This should only be set to <code>false</code>
+ * if a JGroups release is used that itself prevents such classloader leaks.
+ *
+ * @param manageChannelThreadPools <code>true</code> if the pools and
+ * factories should be overridden.
+ */
public void setManageChannelThreadPools(boolean manageChannelThreadPools)
{
this.manageChannelThreadPools = manageChannelThreadPools;
}
+ /**
+ * Gets whether {@link #createMultiplexerChannel(String, String)} should
+ * create a synthetic singleton name attribute for a channel's transport
+ * protocol if one isn't configured. If this is <code>false</code> and
+ * no <code>singleton_name</code> is configured,
+ * {@link #createMultiplexerChannel(String, String)} will throw an
+ * <code>IllegalStateException</code>.
+ *
+ * @return <code>true</code> if synthetic singleton names should be created.
+ * Default is <code>true</code>.
+ */
public boolean getAddMissingSingletonName()
{
return addMissingSingletonName;
}
+ /**
+ * Sets whether {@link #createMultiplexerChannel(String, String)} should
+ * create a synthetic singleton name attribute for a channel's transport
+ * protocol if one isn't configured.
+ *
+ * @param addMissingSingletonName <code>true</code> if synthetic singleton
+ * names should be created.
+ */
public void setAddMissingSingletonName(boolean addMissingSingletonName)
{
this.addMissingSingletonName = addMissingSingletonName;
Modified: trunk/cluster/src/main/org/jboss/ha/framework/server/JChannelFactoryMBean.java
===================================================================
--- trunk/cluster/src/main/org/jboss/ha/framework/server/JChannelFactoryMBean.java 2008-04-22 16:35:36 UTC (rev 72579)
+++ trunk/cluster/src/main/org/jboss/ha/framework/server/JChannelFactoryMBean.java 2008-04-22 16:46:06 UTC (rev 72580)
@@ -12,7 +12,7 @@
* <p>
* The plain-old-java-interface for the channel factory is
* <code>org.jgroups.ChannelFactory</code>; users are encouraged to dependency
- * inject the
+ * inject a <code>org.jgroups.ChannelFactory</code>.
*
*
* @author Bela Ban
@@ -129,7 +129,9 @@
void clearConfigurations();
/**
- * Create a non-multiplexed {@link Channel} using the given stack.
+ * Create a {@link Channel} using the specified stack. Channel will use a
+ * shared transport if the <code>singleton-name</code> attribute is
+ * set on the stack's transport protocol.
*
* @param stack_name the name of the stack
* @return the channel
@@ -139,32 +141,25 @@
Channel createChannel(String stack_name) throws Exception;
/**
- * Creates an implementation of the Channel using a given stack name and
- * registering it under a given identity.
+ * Creates and returns a shared transport Channel configured with the specified
+ * {@link #getConfig(String) protocol stack configuration}.
* <p>
* <emphasis>NOTE:</emphasis> The implementation of this method is somewhat
* different from what is described in
* {@link org.jgroups.ChannelFactory#createMultiplexerChannel(String, String)}.
- * What type of channel is created depends on whether the specified protocol
- * stack includes the <code>singleton_name</code> attribute in its
- * {@link org.jgroups.protocols.TP transport protocol} configuration:
- * <ul>
- * <li>
- * If <code>singleton_name</code> is not specified, a multiplexer-enabled
- * channel will be returned. This will be an implementation of Channel which
- * keeps track of the provided <code>id</code>, so that it can be attached
- * to each message and be properly dispatched at the receiver.
- * <p>
- * In this case, the given <code>id</code> must be unique per stack name.
- * An Exception will be thrown if an attempt to register a duplicate
- * Channel per stack.
- * </li>
- * <li>
- * If <code>singleton_name</code> is not specified, a non-multiplexer
- * enabled channel that instead uses a shared transport will be returned.
- * The <code>id</code> parameter will be ignored.
- * </li>
- * </ul>
+ * The returned channel will not be an instance of
+ * <code>org.jgroups.mux.MuxChannel</code>; rather a channel that uses a
+ * shared transport will be returned. This will be the case whether or
+ * not the protocol stack specified by <code>stack_name</code> includes
+ * a <code>singleton_name</code> attribute in its
+ * {@link org.jgroups.protocols.TP transport protocol} configuration. If no
+ * <code>singleton_name</code> attribute is present, this factory will create
+ * a synthetic one by prepending "unnamed_" to the provided
+ * <code>id</code> param and will use that for the returned channel's
+ * transport protocol. (Note this will not effect the protocol stack
+ * configuration named by <code>stack_name</code>; i.e. another request
+ * that passes the same <code>stack_name</code> will not inherit the
+ * synthetic singleton name.)
*
* @param stack_name
* The name of the stack to be used. All stacks are defined in
@@ -172,66 +167,31 @@
* {@link #setMultiplexerConfig(Object)} for example. If
* clients attempt to create a Channel for an undefined stack
* name an Exception will be thrown.
- * @param id The identifier used for multiplexing and demultiplexing
- * (dispatching requests to one of possibly multiple receivers).
- * Ignored if a shared transport channel is created.
- * Note that id needs to be a string since it will be shipped
- * with each message. Try to pick a short string, because this is
- * shipped with every message (overhead).
+ * @param id Only used if the transport protocol configuration for the
+ * specified stack does not include the <code>singleton_name</code>
+ * attribute; then it is used to create a synthetic singleton-name
+ * for the channel's protocol stack.
*
- * @return An implementation of Channel either configured to multiplex
- * messages to different services or configured with a shared
- * transport.
+ * @return An implementation of Channel configured with a shared transport.
*
- * @see Multiplexer
- * @see MuxChannel
- *
* @throws ChannelException
*/
Channel createMultiplexerChannel(String stack_name, String id) throws Exception;
/**
- * Creates an implementation of the Channel using a given stack name and
- * registering it under a given identity.
- * <p>
- * <emphasis>NOTE:</emphasis> The implementation of this method is somewhat
- * different from what is described in
- * {@link org.jgroups.ChannelFactory#createMultiplexerChannel(String, String)}.
- * See {@link #createMultiplexerChannel(String, String)} for details.
- * <p>
- * JBoss AS ignores the <code>register_for_state_transfer</code> param,
- * treating it as <code>false</code>. Suppressing the
- * <code>register_for_state_transfer</code> param is necessary
- * to avoid issues that occur with JGroups when it is <code>true</code>.
- * In JBoss AS there is little benefit to setting this to true, as the
- * single-threaded nature of deployments in the AS ensures that services
- * always connect channels and request state transfer in series, with no
- * interleaving.
+ * Creates and returns a shared transport Channel configured with the specified
+ * {@link #getConfig(String) protocol stack configuration}.
*
- * @param stack_name
- * The name of the stack to be used. All stacks are defined in
- * the configuration with which the factory is configured (see
- * {@link #setMultiplexerConfig(Object)} for example. If
- * clients attempt to create a Channel for an undefined stack
- * name an Exception will be thrown.
- * @param id The identifier used for multiplexing and demultiplexing
- * (dispatching requests to one of possibly multiple receivers).
- * Ignored if a shared transport channel is created.
- * Note that id needs to be a string since it will be shipped
- * with each message. Try to pick a short string, because this is
- * shipped with every message (overhead).
+ * See {@link #createMultiplexerChannel(String, String)}; the additional
+ * attributes specified in this overloaded version of that method are ignored.
+ *
* @param register_for_state_transfer ignored in JBoss AS. Treated as <code>false</code>.
*
* @param substate_id ignored in JBoss AS
*
- * @return An implementation of Channel either configured to multiplex
- * messages to different services or configured with a shared
- * transport.
+ * @return An implementation of Channel configured with a shared transport.
*
- * @see Multiplexer
- * @see MuxChannel
- *
* @throws ChannelException
*/
Channel createMultiplexerChannel(String stack_name, String id, boolean register_for_state_transfer, String substate_id) throws Exception;
More information about the jboss-cvs-commits
mailing list