Add explanatory javadoc to all of the testcases for this project.

src/main/java/org/jboss/ejb/_private/NetworkUtil.java

@@ -23,6 +23,9 @@
 import java.net.InetAddress;
 
 /**
+ * Tests for the network utility class, used to determine if an internet address belongs to a particular network, where
+ * the network is defined by a network address and netmask.
+ *
  * @author Jaikiran Pai
  */
 public class NetworkUtil {

src/test/java/org/jboss/ejb/client/ConfigurationBasedEJBClientContextSelectorTestCase.java

@@ -26,7 +26,8 @@
 import org.junit.Test;
 
 /**
- * Tests some basic features of ConfigurationBasedEJBClientContextSelector
+ * Tests some basic features of ConfigurationBasedEJBClientContextSelector, responsible for initialization of
+ * the contextual for EJBClientContext.
  *
  * @author <a href="mailto:jbaesner@redhat.com">Joerg Baesner</a>
  */
@@ -36,8 +37,8 @@ public class ConfigurationBasedEJBClientContextSelectorTestCase {
     private static final String CONFIGURATION_FILE = "wildfly-client.xml";
 
     /**
-     * Do any general setup here
-     * 
+     * Configure the wildfly-client.xml file to be used in initialize the EJBClientConext.
+     *
      * @throws Exception
      */
     @BeforeClass
@@ -50,6 +51,9 @@ public static void beforeClass() throws Exception {
         ClassCallback.beforeClassCallback();
     }
 
+    /**
+     * A test which validates that the EJBCLientContext has been initialized with the configured DeploymentNodeSelector.
+     */
     @Test
     public void testDeploymentNodeSelector() {
         EJBClientContext clientContext = EJBClientContext.getCurrent();
@@ -60,6 +64,9 @@ public void testDeploymentNodeSelector() {
         Assert.assertEquals("Wrong <selectNode> value,", DummyNodeSelector.DEPLOYMENT_NODE_IDENTIFIER, dns.selectNode(null, null, null, null));
     }
 
+    /**
+     * A test which validates that the EJBCLientContext has been initialized with the configured ClusterNodeSelector.
+     */
     @Test
     public void testClusterNodeSelector() {
         EJBClientContext clientContext = EJBClientContext.getCurrent();
@@ -70,12 +77,15 @@ public void testClusterNodeSelector() {
         Assert.assertEquals("Wrong <selectNode> value,", DummyNodeSelector.CLUSTER_NODE_IDENTIFIER, cns.selectNode(null, null, null));
     }
 
+    /**
+     * A test which validates that the EJBCLientContext has been initialized with the configured value for
+     * the max-allowed-connected-nodes property.
+     */
     @Test
     public void testMaximumAllowedClusterNodes() {
         EJBClientContext clientContext = EJBClientContext.getCurrent();
         int nodes = clientContext.getMaximumConnectedClusterNodes();
 
         Assert.assertEquals("Wrong <max-allowed-connected-nodes> value,", 15, nodes);
     }
-
 }

src/test/java/org/jboss/ejb/client/DiscoveryEJBClientInterceptorTestCase.java

@@ -24,12 +24,22 @@
 import org.junit.Test;
 
 /**
- * Tests on DiscoveryEJBClientInterceptor
+ * Tests for the DiscoveryEJBClientInterceptor
  *
  * @author <a href="mailto:lgao@redhat.com">Lin Gao</a>
  */
 public class DiscoveryEJBClientInterceptorTestCase {
 
+    /**
+     * A test for the "blocklist" feature of the DiscoveryEJBClientInterceptor which allows invocation targets
+     * to be added to a blocklist. Presence of a URL on the blocklist eans that they should currently be excluded
+     * from discovery request results. The blocklist has an associated timeout; blocklisted entries are cleared
+     * once their time in the blocklist has passed the timeout to avoid being blocklisted forever.
+     *
+     * THis test validates the addition of a URL to the blicklist, as well as its expiration from the blocklist.
+     *
+     * @throws Exception
+     */
     @Test
     public void testBlocklist() throws Exception {
         long timeout = 1000L;
@@ -44,9 +54,8 @@ public void requestRetry() {
         Assert.assertTrue(DiscoveryEJBClientInterceptor.isBlocklisted(context, destination));
         Assert.assertEquals(1, DiscoveryEJBClientInterceptor.getBlocklist().size());
 
-        // If sleeping for just the timeout duration, the lifespan of
-        // the blocklist may equal to, but not greater than, the configured
-        // timeout, and so will not be removed yet. So sleep a bit longer.
+        // If sleeping for just the timeout duration, the lifespan of the blocklist may equal to, but not greater than,
+        // the configured timeout, and so will not be removed yet. So sleep a bit longer.
         Thread.sleep(timeout * 2);
         Assert.assertFalse(DiscoveryEJBClientInterceptor.isBlocklisted(context, destination));
         Assert.assertEquals(0, DiscoveryEJBClientInterceptor.getBlocklist().size());

src/test/java/org/jboss/ejb/client/EJBRootContextTestCase.java

@@ -9,10 +9,22 @@
 import javax.naming.InvalidNameException;
 import javax.naming.NamingException;
 
+/**
+ * A set of tests which validate that invocation.timeout values set in the properties map of a JNDI context
+ * get propagated to the proxies created from that JNDI context.
+ *
+ * @author unknown
+ */
 public class EJBRootContextTestCase {
 
     private static final String LOOKUP_NAME = "appName/moduleName/distinctName!org.jboss.ejb.client.test.common.Echo";
 
+    /**
+     * Test which validates that an integer-valued invocation.timeout property set in the properties map for
+     * a JNDI context gets passed through to a proxy created from that JNDI context.
+     *
+     * @throws NamingException
+     */
     @Test
     public void testInvocationTimeoutEnvPropertyInteger() throws NamingException {
         FastHashtable<String, Object> env = new FastHashtable<>();
@@ -23,6 +35,12 @@ public void testInvocationTimeoutEnvPropertyInteger() throws NamingException {
         Assert.assertEquals(100, EJBInvocationHandler.forProxy(proxy).getInvocationTimeout());
     }
 
+    /**
+     * Test which validates that a string-valued invocation.timeout property set in the properties map for
+     * a JNDI context gets passed through to a proxy created from that JNDI context.
+     *
+     * @throws NamingException
+     */
     @Test
     public void testInvocationTimeoutEnvPropertyString() throws NamingException {
         FastHashtable<String, Object> env = new FastHashtable<>();
@@ -33,6 +51,12 @@ public void testInvocationTimeoutEnvPropertyString() throws NamingException {
         Assert.assertEquals(100, EJBInvocationHandler.forProxy(proxy).getInvocationTimeout());
     }
 
+    /**
+     * Test which validates that a long-valued invocation.timeout property set in the properties map for
+     * a JNDI context gets passed through to a proxy created from that JNDI context.
+     *
+     * @throws NamingException
+     */
     @Test
     public void testInvocationTimeoutEnvPropertyLong() throws NamingException {
         FastHashtable<String, Object> env = new FastHashtable<>();
@@ -43,6 +67,11 @@ public void testInvocationTimeoutEnvPropertyLong() throws NamingException {
         Assert.assertEquals(100, EJBInvocationHandler.forProxy(proxy).getInvocationTimeout());
     }
 
+    /**
+     * Test which validates that the default invocation.timeout property for a JNDI context is -1.
+     *
+     * @throws NamingException
+     */
     @Test
     public void testInvocationTimeoutEnvPropertyEmpty() throws NamingException {
         FastHashtable<String, Object> env = new FastHashtable<>();

src/test/java/org/jboss/ejb/client/ProxyEqualityTestCase.java

@@ -24,12 +24,20 @@
 import org.junit.Test;
 
 /**
+ * Tests which validate the test for proxy equality works for proxies created by the EJB Client API.
+ *
+ * Proxy equality is based on module name, use of an EJBINvocationHandler and viewType.
+ *
  * @author Stuart Douglas
  */
 public class ProxyEqualityTestCase {
 
+    /**
+     * A test for proxy equality, inequality and use of the correct invocation handler.
+     */
     @Test
     public void testClientProxyEquality() {
+        // create a proxy with appName = a, moduleName = m, beanName = b and distinctName = d
         final StatelessEJBLocator<SimpleInterface> locatorA = new StatelessEJBLocator<SimpleInterface>(SimpleInterface.class, "a", "m", "b", "d");
         SimpleInterface proxyA = EJBClient.createProxy(locatorA);
 
@@ -39,11 +47,15 @@ public void testClientProxyEquality() {
         final StatelessEJBLocator<SimpleInterface> locatorC = new StatelessEJBLocator<SimpleInterface>(SimpleInterface.class, "a", "m", "b", "other");
         SimpleInterface proxyC = EJBClient.createProxy(locatorC);
 
+        // validate proxy equality
         Assert.assertTrue(proxyA.equals(proxyB));
         Assert.assertEquals(proxyA.hashCode(), proxyB.hashCode());
+
+        // valite proxy inequality
         Assert.assertFalse(proxyA.equals(proxyC));
         Assert.assertTrue(proxyA.hashCode() != proxyC.hashCode());
 
+        // validate the proxy was created from EJB Client API
         Assert.assertTrue(EJBClient.isEJBProxy(proxyA));
         Assert.assertTrue(EJBClient.isEJBProxy(proxyB));
         Assert.assertTrue(EJBClient.isEJBProxy(proxyC));

src/test/java/org/jboss/ejb/client/legacy/LegacyPropertiesConfigurationTestCase.java

@@ -6,11 +6,27 @@
 
 import java.io.IOException;
 
+/**
+ * Tests to verify that configuration of the EJBClientContext by a legacy jboss-ejb-client.properties file works
+ * as expected. The jboss-ejb-client.properties file allows configuring invocation-related properties for the
+ * EJBClientContext at three different levels:
+ * - invocations targetting singleton nodes
+ * - invocations targetting clusters
+ * - invocations targetting specific nodes in clusters
+ *
+ * @author <a href="mailto:thofman@redhat.com">Thomas Hofman</a>
+ */
 public class LegacyPropertiesConfigurationTestCase {
 
     private static final String PROPERTIES_FILE_MAX_NODES_SET = "maximum-connected-nodes-jboss-ejb-client.properties";
     private static final String PROPERTIES_FILE_MAX_NODES_NOT_SET = "clustered-jboss-ejb-client.properties";
 
+    /**
+     * Tests that values configured for the cluster property "max-allowed-connected-nodes" are passed through
+     * to the resulting EJBClientContext.
+     *
+     * @throws IOException
+     */
     @Test
     public void testMaximumConnectedNodesSet() throws IOException {
         JBossEJBProperties ejbProperties = JBossEJBProperties.fromClassPath(JBossEJBProperties.class.getClassLoader(), PROPERTIES_FILE_MAX_NODES_SET);
@@ -21,6 +37,12 @@ public void testMaximumConnectedNodesSet() throws IOException {
         Assert.assertEquals(42, context.getMaximumConnectedClusterNodes());
     }
 
+    /**
+     * Tests that default values configured for the cluster property "max-allowed-connected-nodes" are passed through
+     * to the resulting EJBClientContext when the property is not set.
+     *
+     * @throws IOException
+     */
     @Test
     public void testMaximumConnectedNodesNotSet() throws IOException {
         JBossEJBProperties ejbProperties = JBossEJBProperties.fromClassPath(JBossEJBProperties.class.getClassLoader(), PROPERTIES_FILE_MAX_NODES_NOT_SET);

src/test/java/org/jboss/ejb/client/remoting/MethodInvocationRequest.java

@@ -20,6 +20,8 @@
 import java.util.Map;
 
 /**
+ * Test framework class representing a method invocation and its associated data.
+ *
  * @author <a href="mailto:cdewolf@redhat.com">Carlo de Wolf</a>
  */
 public class MethodInvocationRequest {

src/test/java/org/jboss/ejb/client/serialization/ProxySerializationTestCase.java

@@ -34,16 +34,27 @@
 import org.junit.Test;
 
 /**
- * Tests that an Enterprise Bean proxy can be serialized
+ * Tests that validate that an Enterprise Bean proxy can be serialized using JBoss Marshalling.
  *
  * @author Stuart Douglas
  */
 public class ProxySerializationTestCase {
 
+    /**
+     * Tests that marshalling/unmarshalling an EJB proxy to and from a byte stream does not affect
+     * the validity of the proxy.
+     *
+     * @throws IOException
+     * @throws ClassNotFoundException
+     */
     @Test
     public void testProxySerialization() throws IOException, ClassNotFoundException {
+
+        // create a sample EJB client proxy
         final StatelessEJBLocator<SimpleInterface> locator = new StatelessEJBLocator<SimpleInterface>(SimpleInterface.class, "a", "m", "b", "d");
         final Object proxy = EJBClient.createProxy(locator);
+
+        // configure a JBoss Marshalling marshaller and marshall the proxy into a byte array, "bytes"
         final MarshallingConfiguration marshallingConfiguration = new MarshallingConfiguration();
         marshallingConfiguration.setVersion(2);
         org.jboss.marshalling.MarshallerFactory factory = new RiverMarshallerFactory();
@@ -52,10 +63,14 @@ public void testProxySerialization() throws IOException, ClassNotFoundException
         marshaller.start(new OutputStreamByteOutput(bytes));
         marshaller.writeObject(proxy);
         marshaller.finish();
+
+        // configure a JBoss Marshalling unmarshaller and unmarshal the byte array, "bytes", into an Object
         Unmarshaller unmarshaller = factory.createUnmarshaller(marshallingConfiguration);
         ByteArrayInputStream in = new ByteArrayInputStream(bytes.toByteArray());
         unmarshaller.start(new InputStreamByteInput(in));
         Object deserialized = unmarshaller.readObject();
+
+        // check for equality of the original proxy and the marshalled/unmarshalled proxy
         Assert.assertEquals(proxy, deserialized);
     }
 

src/test/java/org/jboss/ejb/client/test/ClassCallback.java

@@ -1,5 +1,8 @@
 package org.jboss.ejb.client.test;
 
+/**
+ * A helper class to allow calling an arbitrary Runnable
+ */
 public class ClassCallback {
     private static volatile Runnable beforeClassCallback;