You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ph...@apache.org on 2013/07/09 16:03:25 UTC
svn commit: r1501274 - in /qpid/proton/trunk:
proton-j/proton-api/src/main/java/org/apache/qpid/proton/driver/
proton-j/proton/src/main/java/org/apache/qpid/proton/logging/
tests/java/org/apache/qpid/proton/systemtests/
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-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org