Author: philharveyonline Date: Tue Jul 9 14:03:25 2013 New Revision: 1501274
URL: http://svn.apache.org/r1501274 Log: NO-JIRA: JavaDoc improvements, and minor tidying up of test and logging code. Modified: qpid/proton/trunk/proton-j/proton-api/src/main/java/org/apache/qpid/proton/driver/Connector.java qpid/proton/trunk/proton-j/proton-api/src/main/java/org/apache/qpid/proton/driver/Driver.java qpid/proton/trunk/proton-j/proton/src/main/java/org/apache/qpid/proton/logging/LoggingProtocolTracer.java qpid/proton/trunk/tests/java/org/apache/qpid/proton/systemtests/ProtonEngineExampleTest.java Modified: qpid/proton/trunk/proton-j/proton-api/src/main/java/org/apache/qpid/proton/driver/Connector.java URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-j/proton-api/src/main/java/org/apache/qpid/proton/driver/Connector.java?rev=1501274&r1=1501273&r2=1501274&view=diff ============================================================================== --- qpid/proton/trunk/proton-j/proton-api/src/main/java/org/apache/qpid/proton/driver/Connector.java (original) +++ qpid/proton/trunk/proton-j/proton-api/src/main/java/org/apache/qpid/proton/driver/Connector.java Tue Jul 9 14:03:25 2013 @@ -25,43 +25,54 @@ import org.apache.qpid.proton.engine.Con import org.apache.qpid.proton.engine.Sasl; /** - * Client API + * Intermediates between a proton engine {@link Connection} and the I/O + * layer. + * + * The top half of the engine can be access via {@link #getConnection()}. + * The bottom half of the engine is used by {@link #process()}. + * Stores application specific context using {@link #setContext(Object)}. + * + * Implementations are not necessarily thread-safe. * * @param <C> application supplied context */ public interface Connector<C> { - /** Service the given connector. - * + /** * Handle any inbound data, outbound data, or timing events pending on * the connector. - * + * Typically, applications repeatedly invoke this method + * during the lifetime of a connection. */ void process() throws IOException; - /** Access the listener which opened this connector. + /** + * Access the listener which opened this connector. * - * @return the listener which created this connector, or NULL if the + * @return the listener which created this connector, or null if the * connector has no listener (e.g. an outbound client * connection). */ @SuppressWarnings("rawtypes") Listener listener(); - /** Access the Authentication and Security context of the connector. + /** + * Access the Authentication and Security context of the connector. * * @return the Authentication and Security context for the connector, - * or NULL if none. + * or null if none. */ Sasl sasl(); - /** Access the AMQP Connection associated with the connector. + /** + * Access the AMQP Connection associated with the connector. * - * @return the connection context for the connector, or NULL if none. + * @return the connection context for the connector, or null if none. */ Connection getConnection(); - /** Assign the AMQP Connection associated with the connector. + /** + * Assign the AMQP Connection associated with the connector. * * @param connection the connection to associate with the connector. */ @@ -79,27 +90,27 @@ public interface Connector<C> */ C getContext(); - /** Assign a new application context to the connector. + /** + * Assign a new application context to the connector. * * @param context new application context to associate with the connector */ void setContext(C context); - /** Close the socket used by the connector. - * + /** + * Close the socket used by the connector. */ void close(); - /** Determine if the connector is closed. - * - * @return True if closed, otherwise false + /** + * Determine if the connector is closed. */ boolean isClosed(); - /** Destructor for the given connector. + /** + * Destructor for the given connector. * * Assumes the connector's socket has been closed prior to call. - * */ void destroy(); } Modified: qpid/proton/trunk/proton-j/proton-api/src/main/java/org/apache/qpid/proton/driver/Driver.java URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-j/proton-api/src/main/java/org/apache/qpid/proton/driver/Driver.java?rev=1501274&r1=1501273&r2=1501274&view=diff ============================================================================== --- qpid/proton/trunk/proton-j/proton-api/src/main/java/org/apache/qpid/proton/driver/Driver.java (original) +++ qpid/proton/trunk/proton-j/proton-api/src/main/java/org/apache/qpid/proton/driver/Driver.java Tue Jul 9 14:03:25 2013 @@ -25,38 +25,44 @@ import java.nio.channels.SelectableChann import java.nio.channels.ServerSocketChannel; /** - * The Driver interface provides an abstraction for an implementation of - * a driver for the proton engine. - * A driver is responsible for providing input, output, and tick events, - * to the bottom half of the engine API. TODO See ::pn_input, ::pn_output, and - * ::pn_tick. - * The driver also provides an interface for the application to access, - * the top half of the API when the state of the engine may have changed - * due to I/O or timing events. Additionally the driver incorporates the SASL - * engine as well in order to provide a complete network stack: AMQP over SASL - * over TCP. + * A driver for the proton engine. + * + * Manages {@link Connector}'s and {@link Listener}'s, which act as intermediaries between + * the proton engine and the network. + * + * Provides methods for the application to access the "top half" of the engine API when the state + * of the engine may have changed due to I/O or timing events - see {@link #connector()}. + * + * Connectors incorporate the SASL engine in order to provide a complete network stack: + * AMQP over SASL over TCP. + * + * Unless otherwise stated, methods on Driver implementations are not necessarily thread-safe. */ - public interface Driver { /** - * Force wait() to return + * Force {@link #doWait(long)} to return. + * + * If the driver is not currently waiting then the next invocation of {@link #doWait(long)} + * will return immediately unless the {@link #connector()} method is invoked in the meantime. * + * Thread-safe. */ void wakeup(); /** - * Wait for an active connector or listener + * Wait for an active connector or listener, or for {@link #wakeup()} to be called. * - * @param timeout maximum time in milliseconds to wait. - * 0 means infinite wait + * Thread-safe. + * + * @param timeout maximum time in milliseconds to wait. 0 means wait indefinitely. */ void doWait(long timeout); /** * Get the next listener with pending data in the driver. * - * @return NULL if no active listener available + * @return null if no active listener available */ @SuppressWarnings("rawtypes") Listener listener(); @@ -67,7 +73,9 @@ public interface Driver * Returns the next connector with pending inbound data, available capacity * for outbound data, or pending tick. * - * @return NULL if no active connector available + * Clears the wake-up status that is set by {@link #wakeup()}. + * + * @return null if no active connector available */ @SuppressWarnings("rawtypes") Connector connector(); @@ -84,7 +92,7 @@ public interface Driver * @param port local port to listen on * @param context application-supplied, can be accessed via * {@link Listener#getContext() getContext()} method on a listener. - * @return a new listener on the given host:port, NULL if error + * @return a new listener on the given host:port, null if error */ <C> Listener<C> createListener(String host, int port, C context); @@ -94,7 +102,7 @@ public interface Driver * @param c existing SocketChannel for listener to listen on * @param context application-supplied, can be accessed via * {@link Listener#getContext() getContext()} method on a listener. - * @return a new listener on the given channel, NULL if error + * @return a new listener on the given channel, null if error */ <C> Listener<C> createListener(ServerSocketChannel c, C context); @@ -106,7 +114,7 @@ public interface Driver * @param context application-supplied, can be accessed via * {@link Connector#getContext() getContext()} method on a listener. * - * @return a new connector to the given remote, or NULL on error. + * @return a new connector to the given remote, or null on error. */ <C> Connector<C> createConnector(String host, int port, C context); @@ -117,7 +125,7 @@ public interface Driver * @param context application-supplied, can be accessed via * {@link Connector#getContext() getContext()} method on a listener. * - * @return a new connector to the given host:port, NULL if error. + * @return a new connector to the given host:port, null if error. */ <C> Connector<C> createConnector(SelectableChannel fd, C context); Modified: qpid/proton/trunk/proton-j/proton/src/main/java/org/apache/qpid/proton/logging/LoggingProtocolTracer.java URL: http://svn.apache.org/viewvc/qpid/proton/trunk/proton-j/proton/src/main/java/org/apache/qpid/proton/logging/LoggingProtocolTracer.java?rev=1501274&r1=1501273&r2=1501274&view=diff ============================================================================== --- qpid/proton/trunk/proton-j/proton/src/main/java/org/apache/qpid/proton/logging/LoggingProtocolTracer.java (original) +++ qpid/proton/trunk/proton-j/proton/src/main/java/org/apache/qpid/proton/logging/LoggingProtocolTracer.java Tue Jul 9 14:03:25 2013 @@ -34,6 +34,7 @@ public class LoggingProtocolTracer imple public LoggingProtocolTracer() { + this("Transport"); } public LoggingProtocolTracer(String logMessagePrefix) Modified: qpid/proton/trunk/tests/java/org/apache/qpid/proton/systemtests/ProtonEngineExampleTest.java URL: http://svn.apache.org/viewvc/qpid/proton/trunk/tests/java/org/apache/qpid/proton/systemtests/ProtonEngineExampleTest.java?rev=1501274&r1=1501273&r2=1501274&view=diff ============================================================================== --- qpid/proton/trunk/tests/java/org/apache/qpid/proton/systemtests/ProtonEngineExampleTest.java (original) +++ qpid/proton/trunk/tests/java/org/apache/qpid/proton/systemtests/ProtonEngineExampleTest.java Tue Jul 9 14:03:25 2013 @@ -26,6 +26,7 @@ import static org.apache.qpid.proton.eng import static org.apache.qpid.proton.engine.EndpointState.CLOSED; import static org.apache.qpid.proton.engine.EndpointState.UNINITIALIZED; import static org.apache.qpid.proton.systemtests.TestLoggingHelper.bold; +import static org.apache.qpid.proton.systemtests.engine.ProtonFactoryTestFixture.isProtonJ; import static org.junit.Assert.assertNull; import static org.junit.Assert.assertSame; @@ -82,8 +83,6 @@ public class ProtonEngineExampleTest private final EngineFactory _engineFactory = new ProtonFactoryLoader<EngineFactory>(EngineFactory.class).loadFactory(); private final MessageFactory _messageFactory = new ProtonFactoryLoader<MessageFactory>(MessageFactory.class).loadFactory(); - private final boolean _isEngineProtonJ = !_engineFactory.getClass().getSimpleName().startsWith("JNI"); - @Test public void test() throws Exception { @@ -196,7 +195,7 @@ public class ProtonEngineExampleTest assertEquals("For simplicity, assume the sender can accept all the data", lengthOfEncodedMessage, numberOfBytesAcceptedBySender); - if (_isEngineProtonJ) + if (isProtonJ(_engineFactory)) { // TODO PROTON-261: Proton-c ProtonJNI.pn_delivery_local_state is returning 0, which doesn't map to an // value within the C enum. @@ -214,7 +213,7 @@ public class ProtonEngineExampleTest _server.delivery = _server.connection.getWorkHead(); assertEquals("The received delivery should be on our receiver", _server.receiver, _server.delivery.getLink()); - if (_isEngineProtonJ) + if (isProtonJ(_engineFactory)) { assertNull(_server.delivery.getLocalState()); assertNull(_server.delivery.getRemoteState()); --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org
