You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hc.apache.org by ol...@apache.org on 2009/01/12 20:55:55 UTC
svn commit: r733879 - in /httpcomponents/httpcore/trunk:
module-main/src/main/java/org/apache/http/params/
module-main/src/main/java/org/apache/http/protocol/
module-nio/src/main/java/org/apache/http/impl/nio/reactor/
module-nio/src/main/java/org/apach...
Author: olegk
Date: Mon Jan 12 11:55:23 2009
New Revision: 733879
URL: http://svn.apache.org/viewvc?rev=733879&view=rev
Log:
Javadoc updates
Added:
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/package.html
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/package.html
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/package.html
Modified:
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/package.html
httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/package.html
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/AbstractIOReactor.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/ChannelEntry.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/package.html
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/BufferingNHttpEntity.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ConsumingNHttpEntity.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentBufferEntity.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentInputStream.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentListener.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentOutputStream.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NByteArrayEntity.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NFileEntity.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NHttpEntityWrapper.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NStringEntity.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ProducingNHttpEntity.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorPNames.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorParams.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpClientHandler.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpServiceHandler.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/EventListener.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/HttpRequestExecutionHandler.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandler.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerRegistry.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerResolver.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpResponseTrigger.java
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/package.html?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/package.html (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/package.html Mon Jan 12 11:55:23 2009
@@ -34,7 +34,7 @@
-->
</head>
<body>
-The parameterization framework for HTTP components.
-
+The parameterization framework for HTTP components. This package also provides
+core protocol and I/O parameters.
</body>
</html>
Modified: httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/package.html?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/package.html (original)
+++ httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/package.html Mon Jan 12 11:55:23 2009
@@ -34,79 +34,8 @@
-->
</head>
<body>
-HTTP protocol execution framework.
-
-Apart from simply sending and receiving messages, there are a lot
-of things to consider when communicating with HTTP. Many details
-such as transport encodings or connection management are handled
-by setting up or interpreting
-{@link org.apache.http.Header headers} in the messages.
-In order to relieve applications from the responsibility of
-implementing these nitty-gritty details of the protocol,
-HTTP components provides an execution framework that sets up
-some of the headers before sending a message, and interprets
-headers when a message has been received.
-<br/>
-An HTTP {@link org.apache.http.protocol.HttpProcessor processor}
-typically keeps lists of so-called interceptors that will be executed
-before a message is sent and after it has been received.
-An application should initialize a processor, set up the lists
-with the required and desired processors, and then communicate
-through that processor. There are four kinds of interceptors,
-depending on whether they act on
-{@link org.apache.http.HttpRequestInterceptor requests} or
-{@link org.apache.http.HttpResponseInterceptor responses},
-on the client or server side:
-
-<table border="1" cellpadding="5">
-<tr><th></th>
- <th>Client</th>
- <th>Server</th>
-</tr>
-<tr><th>Request</th>
- <td>prepares headers before a request is sent</td>
- <td>interprets headers when a request is received</td>
-</tr>
-<tr><th>Response</th>
- <td>interprets headers when a response is received</td>
- <td>prepares headers before a response is sent</td>
-</tr>
-</table>
-
-<p>
-{@link org.apache.http.protocol.HttpRequestExecutor HttpRequestExecutor}
-is a processor for the client side,
-{@link org.apache.http.protocol.HttpService HttpService}
-for the server side.
-On the client side, a {@link org.apache.http.protocol.HttpContext context}
-is used to tie together a request, the response to it, and other data
-that might be associated with the request execution. It is passed to
-the request executor whenever needed.
-</p>
-
-<p>
-<font size="+1">
-<i>
-Information about required and recommended interceptors for the
-client side will be provided elsewhere. For the time being, please
-refer to the comments in the example applications or ask on
-one of the mailing lists.
-</i>
-</font>
-</p>
-
-<p>
-<b>Note:</b>
-If you want to develop a server-side application, we recommend that
-you implement your application as a servlet running in a servlet engine
-like <a href="http://tomcat.apache.org/">Tomcat</a> or full-blown
-JSEE container like <a href="http://geronimo.apache.org/">Geronimo</a>.
-If you prefer to implement a server-side application based on our
-{@link org.apache.http.protocol.HttpService HttpService}, we'll
-assume that you know what you're doing and that you don't need
-help in figuring out which interceptors need to be configured.
-</p>
-
-
+HTTP protocol execution framework. This package contains common protocol
+aspects implemented as protocol interceptors as well as protocol handler
+implementations based on classic (blocking) I/O model.
</body>
</html>
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/AbstractIOReactor.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/AbstractIOReactor.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/AbstractIOReactor.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/AbstractIOReactor.java Mon Jan 12 11:55:23 2009
@@ -52,6 +52,11 @@
import org.apache.http.nio.reactor.IOReactorStatus;
import org.apache.http.nio.reactor.IOSession;
+/**
+ * Generic implementation of {@link IOReactor} that can used as a subclass
+ * for more specialized I/O reactors. It is based on a single {@link Selector}
+ * instance.
+ */
public abstract class AbstractIOReactor implements IOReactor {
private volatile IOReactorStatus status;
@@ -63,6 +68,11 @@
private final Queue<IOSession> closedSessions;
private final Queue<ChannelEntry> newChannels;
+ /**
+ * Creates new AbstractIOReactor instance.
+ * @param selectTimeout the select timeout.
+ * @throws IOReactorException in case if a non-recoverable I/O error.
+ */
public AbstractIOReactor(long selectTimeout) throws IOReactorException {
super();
if (selectTimeout <= 0) {
@@ -81,28 +91,83 @@
this.status = IOReactorStatus.INACTIVE;
}
+ /**
+ * Triggered when the key signals {@link SelectionKey#OP_ACCEPT} readiness.
+ *
+ * @param key the selection key.
+ */
protected abstract void acceptable(SelectionKey key);
+ /**
+ * Triggered when the key signals {@link SelectionKey#OP_CONNECT} readiness.
+ *
+ * @param key the selection key.
+ */
protected abstract void connectable(SelectionKey key);
+ /**
+ * Triggered when the key signals {@link SelectionKey#OP_READ} readiness.
+ *
+ * @param key the selection key.
+ */
protected abstract void readable(SelectionKey key);
+ /**
+ * Triggered when the key signals {@link SelectionKey#OP_WRITE} readiness.
+ *
+ * @param key the selection key.
+ */
protected abstract void writable(SelectionKey key);
+ /**
+ * Triggered to verify whether the key has not timed out.
+ *
+ * @param key the selection key.
+ * @param current time as long value.
+ */
protected abstract void timeoutCheck(SelectionKey key, long now);
+ /**
+ * Triggered to validate keys currently registered with the selector.
+ *
+ * @param keys all selection keys registered with the selector.
+ */
protected abstract void validate(Set<SelectionKey> keys);
+ /**
+ * Triggered when new session has been created.
+ *
+ * @param key the selection key.
+ * @param session new I/O session.
+ */
protected abstract void sessionCreated(SelectionKey key, IOSession session);
- protected abstract IOSession getSession(SelectionKey key);
-
+ /**
+ * Triggered when a session has been closed.
+ *
+ * @param session closed I/O session.
+ */
protected abstract void sessionClosed(IOSession session);
+ /**
+ * Obtains {@link IOSession} instance associated with the given selection
+ * key.
+ *
+ * @param key the selection key.
+ * @return I/O session.
+ */
+ protected abstract IOSession getSession(SelectionKey key);
+
public IOReactorStatus getStatus() {
return this.status;
}
+ /**
+ * Adds new channel entry. The channel will be asynchronously registered
+ * with the selector.
+ *
+ * @param channelEntry the channel entry.
+ */
public void addChannel(final ChannelEntry channelEntry) {
if (channelEntry == null) {
throw new IllegalArgumentException("Channel entry may not be null");
@@ -183,7 +248,12 @@
}
selectedKeys.clear();
}
-
+
+ /**
+ * Processes new event on the given selection key.
+ *
+ * @param key the selection key that triggered an event.
+ */
protected void processEvent(final SelectionKey key) {
try {
if (key.isAcceptable()) {
@@ -205,6 +275,11 @@
}
}
+ /**
+ * Queues the given I/O session to be processed asynchronously as closed.
+ *
+ * @param session the closed I/O session.
+ */
protected void queueClosedSession(final IOSession session) {
if (session != null) {
this.closedSessions.add(session);
@@ -282,6 +357,9 @@
}
}
+ /**
+ * Closes out all I/O sessions maintained by this I/O reactor.
+ */
protected void closeSessions() {
synchronized (this.sessions) {
for (Iterator<IOSession> it = this.sessions.iterator(); it.hasNext(); ) {
@@ -291,6 +369,10 @@
}
}
+ /**
+ * Closes out all new channels pending registration with the selector of
+ * this I/O reactor.
+ */
protected void closeNewChannels() throws IOReactorException {
ChannelEntry entry;
while ((entry = this.newChannels.poll()) != null) {
@@ -306,6 +388,10 @@
}
}
+ /**
+ * Closes out all active channels registered with the selector of
+ * this I/O reactor.
+ */
protected void closeActiveChannels() throws IOReactorException {
Set<SelectionKey> keys = this.selector.keys();
for (Iterator<SelectionKey> it = keys.iterator(); it.hasNext(); ) {
@@ -324,6 +410,9 @@
}
}
+ /**
+ * Attempts graceful shutdown of this I/O reactor.
+ */
public void gracefulShutdown() {
if (this.status != IOReactorStatus.ACTIVE) {
// Already shutting down
@@ -333,6 +422,9 @@
this.selector.wakeup();
}
+ /**
+ * Attempts force-shutdown of this I/O reactor.
+ */
public void hardShutdown() throws IOReactorException {
if (this.status == IOReactorStatus.SHUT_DOWN) {
// Already shut down
@@ -343,6 +435,13 @@
closeActiveChannels();
}
+ /**
+ * Blocks for the given period of time in milliseconds awaiting
+ * the completion of the reactor shutdown.
+ *
+ * @param timeout the maximum wait time.
+ * @throws InterruptedException if interrupted.
+ */
public void awaitShutdown(long timeout) throws InterruptedException {
synchronized (this.shutdownMutex) {
long deadline = System.currentTimeMillis() + timeout;
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/ChannelEntry.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/ChannelEntry.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/ChannelEntry.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/ChannelEntry.java Mon Jan 12 11:55:23 2009
@@ -33,11 +33,27 @@
import java.nio.channels.SocketChannel;
+/**
+ * {@link SocketChannel} entry maintained by the I/O reactor. If the channel
+ * represents an outgoing client connection, this entry also contains the
+ * original {@link SessionRequestImpl} used to request it.
+ *
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
+ */
public class ChannelEntry {
private final SocketChannel channel;
private final SessionRequestImpl sessionRequest;
+ /**
+ * Creates new ChannelEntry.
+ *
+ * @param channel the channel
+ * @param sessionRequest original session request. Can be <code>null</code>
+ * if the channel represents an incoming server-side connection.
+ */
public ChannelEntry(final SocketChannel channel, final SessionRequestImpl sessionRequest) {
super();
if (channel == null) {
@@ -47,14 +63,33 @@
this.sessionRequest = sessionRequest;
}
+ /**
+ * Creates new ChannelEntry.
+ *
+ * @param channel the channel.
+ */
public ChannelEntry(final SocketChannel channel) {
this(channel, null);
}
+ /**
+ * Returns the original session request, if available. If the channel
+ * entry represents an incoming server-side connection, returns
+ * <code>null</code>.
+ *
+ * @return the original session request, if client-side channel,
+ * <code>null</code> otherwise.
+ */
public SessionRequestImpl getSessionRequest() {
return this.sessionRequest;
}
+ /**
+ * Returns the original session request attachment, if available.
+ *
+ * @return the original session request attachment, if available,
+ * <code>null</code> otherwise.
+ */
public Object getAttachment() {
if (this.sessionRequest != null) {
return this.sessionRequest.getAttachment();
@@ -63,6 +98,11 @@
}
}
+ /**
+ * Returns the channel.
+ *
+ * @return the channel.
+ */
public SocketChannel getChannel() {
return this.channel;
}
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/package.html?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/package.html (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/impl/nio/reactor/package.html Mon Jan 12 11:55:23 2009
@@ -34,8 +34,8 @@
-->
</head>
<body>
-NIO based implementations of HttpCore interfaces.
-This includes default implementations for the interfaces in
-{@link org.apache.http.nio org.apache.http.nio}.
+Default implementations for interfaces in
+{@link org.apache.http.nio org.apache.http.nio} including default
+I/O reactor implementations and support for SSL/TLS transport security.
</body>
</html>
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/BufferingNHttpEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/BufferingNHttpEntity.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/BufferingNHttpEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/BufferingNHttpEntity.java Mon Jan 12 11:55:23 2009
@@ -81,13 +81,19 @@
public void consumeContent() throws IOException {
}
+ /**
+ * Obtains entity's content as {@link InputStream}.
+ *
+ * @throws IllegalStateException if content of the entity has not been
+ * fully received or has already been consumed.
+ */
@Override
public InputStream getContent() throws IOException {
if (!this.finished) {
throw new IllegalStateException("Entity content has not been fully received");
}
if (this.consumed) {
- throw new IllegalStateException("Entity content has not been consumed");
+ throw new IllegalStateException("Entity content has been consumed");
}
this.consumed = true;
return new ContentInputStream(this.buffer);
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ConsumingNHttpEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ConsumingNHttpEntity.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ConsumingNHttpEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ConsumingNHttpEntity.java Mon Jan 12 11:55:23 2009
@@ -38,7 +38,7 @@
import org.apache.http.nio.IOControl;
/**
- * A non-blocking {@link HttpEntity} that allows content to be consumed from a
+ * A non-blocking {@link HttpEntity} that allows content to be streamed from a
* {@link ContentDecoder}.
*
* @author <a href="mailto:sberlin at gmail.com">Sam Berlin</a>
@@ -50,6 +50,9 @@
* {@link IOControl} instance passed as a parameter to the method can be
* used to suspend input events if the entity is temporarily unable to
* allocate more storage to accommodate all incoming content.
+ *
+ * @param decoder content decoder.
+ * @param ioctrl I/O control of the underlying connection.
*/
void consumeContent(ContentDecoder decoder, IOControl ioctrl) throws IOException;
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentBufferEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentBufferEntity.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentBufferEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentBufferEntity.java Mon Jan 12 11:55:23 2009
@@ -36,11 +36,20 @@
import org.apache.http.entity.BasicHttpEntity;
import org.apache.http.nio.util.ContentInputBuffer;
+/**
+ * HTTP entity wrapper whose content is provided by a
+ * {@link ContentInputBuffer}.
+ */
public class ContentBufferEntity extends BasicHttpEntity {
- /** The wrapped entity. */
private HttpEntity wrappedEntity;
+ /**
+ * Creates new instance of ContentBufferEntity.
+ *
+ * @param entity the original entity.
+ * @param buffer the content buffer.
+ */
public ContentBufferEntity(final HttpEntity entity, final ContentInputBuffer buffer) {
super();
if (entity == null) {
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentInputStream.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentInputStream.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentInputStream.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentInputStream.java Mon Jan 12 11:55:23 2009
@@ -36,6 +36,9 @@
import org.apache.http.nio.util.ContentInputBuffer;
+/**
+ * {@link InputStream} adaptor for {@link ContentInputBuffer}.
+ */
public class ContentInputStream extends InputStream {
private final ContentInputBuffer buffer;
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentListener.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentListener.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentListener.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentListener.java Mon Jan 12 11:55:23 2009
@@ -1,7 +1,7 @@
/*
- * $HeadURL:$
- * $Revision:$
- * $Date:$
+ * $HeadURL$
+ * $Revision$
+ * $Date$
*
* ====================================================================
* Licensed to the Apache Software Foundation (ASF) under one
@@ -43,8 +43,12 @@
/**
* Notification that content is available to be read from the decoder.
+ *
+ * @param decoder content decoder.
+ * @param ioctrl I/O control of the underlying connection.
*/
- void contentAvailable(ContentDecoder decoder, IOControl ioctrl) throws IOException;
+ void contentAvailable(ContentDecoder decoder, IOControl ioctrl)
+ throws IOException;
/**
* Notification that any resources allocated for reading can be released.
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentOutputStream.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentOutputStream.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentOutputStream.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ContentOutputStream.java Mon Jan 12 11:55:23 2009
@@ -36,6 +36,9 @@
import org.apache.http.nio.util.ContentOutputBuffer;
+/**
+ * {@link OutputStream} adaptor for {@link ContentOutputBuffer}.
+ */
public class ContentOutputStream extends OutputStream {
private final ContentOutputBuffer buffer;
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NByteArrayEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NByteArrayEntity.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NByteArrayEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NByteArrayEntity.java Mon Jan 12 11:55:23 2009
@@ -43,8 +43,9 @@
import org.apache.http.nio.protocol.AsyncNHttpServiceHandler;
/**
- * An entity whose content is retrieved from a byte array.
- *
+ * A simple self contained, repeatable non-blocking entity that retrieves
+ * its content from a byte array.
+ *
* @author <a href="mailto:sberlin at gmail.com">Sam Berlin</a>
*
* @version $Revision$
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NFileEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NFileEntity.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NFileEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NFileEntity.java Mon Jan 12 11:55:23 2009
@@ -45,8 +45,11 @@
import org.apache.http.nio.IOControl;
/**
- * An entity whose content is retrieved from from a file.
- *
+ * A self contained, repeatable non-blocking entity that retrieves its content
+ * from a file. This class is mostly used to stream large files of different
+ * types, so one needs to supply the content type of the file to make sure
+ * the content can be correctly recognized and processed by the recipient.
+ *
* @author <a href="mailto:sberlin at gmail.com">Sam Berlin</a>
*
* @version $Revision$
@@ -60,6 +63,17 @@
private long idx = -1;
private boolean useFileChannels;
+ /**
+ * Creates new instance of NFileEntity from the given source {@link File}
+ * with the given content type. If <code>useFileChannels</code> is set to
+ * <code>true</code>, the entity will try to use {@link FileContentEncoder}
+ * interface to stream file content directly from the file channel.
+ *
+ * @param file the source file.
+ * @param contentType the content type of the file.
+ * @param useFileChannels flag whether the direct transfer from the file
+ * channel should be attempted.
+ */
public NFileEntity(final File file, final String contentType, boolean useFileChannels) {
if (file == null) {
throw new IllegalArgumentException("File may not be null");
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NHttpEntityWrapper.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NHttpEntityWrapper.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NHttpEntityWrapper.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NHttpEntityWrapper.java Mon Jan 12 11:55:23 2009
@@ -43,6 +43,10 @@
import org.apache.http.nio.ContentEncoder;
import org.apache.http.nio.IOControl;
+/**
+ * {@link ProducingNHttpEntity} compatibility adaptor for blocking HTTP
+ * entities.
+ */
public class NHttpEntityWrapper
extends HttpEntityWrapper implements ProducingNHttpEntity {
@@ -55,6 +59,9 @@
this.buffer = ByteBuffer.allocate(4096);
}
+ /**
+ * This method throws {@link UnsupportedOperationException}.
+ */
@Override
public InputStream getContent() throws IOException, UnsupportedOperationException {
throw new UnsupportedOperationException("Does not support blocking methods");
@@ -65,6 +72,9 @@
return true;
}
+ /**
+ * This method throws {@link UnsupportedOperationException}.
+ */
@Override
public void writeTo(OutputStream out) throws IOException, UnsupportedOperationException {
throw new UnsupportedOperationException("Does not support blocking methods");
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NStringEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NStringEntity.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NStringEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/NStringEntity.java Mon Jan 12 11:55:23 2009
@@ -45,8 +45,9 @@
import org.apache.http.protocol.HTTP;
/**
- * An entity whose content is retrieved from a string.
- *
+ * A simple, self contained, repeatable non-blocking entity that retrieves
+ * its content from a {@link String} object.
+ *
* @author <a href="mailto:sberlin at gmail.com">Sam Berlin</a>
*
* @version $Revision$
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ProducingNHttpEntity.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ProducingNHttpEntity.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ProducingNHttpEntity.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/ProducingNHttpEntity.java Mon Jan 12 11:55:23 2009
@@ -38,7 +38,8 @@
import org.apache.http.nio.IOControl;
/**
- * An {@link HttpEntity} that writes content to a {@link ContentEncoder}.
+ * An {@link HttpEntity} that can stream content out into a
+ * {@link ContentEncoder}.
*
* @author <a href="mailto:sberlin at gmail.com">Sam Berlin</a>
*/
@@ -49,9 +50,12 @@
* {@link IOControl} instance passed as a parameter to the method can be
* used to suspend output events if the entity is temporarily unable to
* produce more content.
- * <b/>
+ * <p>
* When all content is finished, this <b>MUST</b> call {@link ContentEncoder#complete()}.
* Failure to do so could result in the entity never being written.
+ *
+ * @param encoder content encoder.
+ * @param ioctrl I/O control of the underlying connection.
*/
void produceContent(ContentEncoder encoder, IOControl ioctrl) throws IOException;
Added: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/package.html?rev=733879&view=auto
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/package.html (added)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/entity/package.html Mon Jan 12 11:55:23 2009
@@ -0,0 +1,52 @@
+<html>
+<head>
+<!--
+/*
+ * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/entity/package.html $
+ * $Revision: 726457 $
+ * $Date: 2008-12-14 15:55:26 +0100 (Sun, 14 Dec 2008) $
+ *
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation. For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+-->
+</head>
+<body>
+Representations for non-blocking HTTP message entities.
+
+An {@link org.apache.http.HttpEntity entity} is the optional content of a
+{@link org.apache.http.HttpMessage message}.
+This package provides a basic selection of entity implementations
+that can obtain content from
+{@link org.apache.http.nio.entity.NByteArrayEntity byte array},
+{@link org.apache.http.nio.entity.NStringEntity string},
+{@link org.apache.http.nio.entity.NFileEntity file}, or through an
+{@link org.apache.http.nio.entity.NHttpEntityWrapper compatibility adaptor}
+for blocking HTTP entities.
+If a message is received from an open non-blocking connection, usually it is
+represented by
+{@link org.apache.http.nio.entity.ConsumingNHttpEntity consuming} entity.
+</body>
+</html>
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorPNames.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorPNames.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorPNames.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorPNames.java Mon Jan 12 11:55:23 2009
@@ -31,9 +31,8 @@
package org.apache.http.nio.params;
-
/**
- * Parameter names for reactors in HttpNIO.
+ * Parameter names for I/O reactors.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorParams.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorParams.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorParams.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/NIOReactorParams.java Mon Jan 12 11:55:23 2009
@@ -34,12 +34,7 @@
import org.apache.http.params.HttpParams;
/**
- * This class implements an adaptor around the {@link HttpParams} interface
- * to simplify manipulation of the NIO reactor specific parameters.
- * <br/>
- * Note that the <i>implements</i> relation to {@link NIOReactorPNames}
- * is for compatibility with existing application code only. References to
- * the parameter names should use the interface, not this class.
+ * Utility class for accessing I/O reactor parameters in {@link HttpParams}.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
Added: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/package.html?rev=733879&view=auto
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/package.html (added)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/params/package.html Mon Jan 12 11:55:23 2009
@@ -0,0 +1,39 @@
+<html>
+<head>
+<!--
+/*
+ * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/params/package.html $
+ * $Revision: 496070 $
+ * $Date: 2007-01-14 13:18:34 +0100 (Sun, 14 Jan 2007) $
+ *
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation. For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+-->
+</head>
+<body>
+HTTP parameters for I/O reactors based on NIO model.
+</body>
+</html>
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpClientHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpClientHandler.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpClientHandler.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpClientHandler.java Mon Jan 12 11:55:23 2009
@@ -57,14 +57,14 @@
* blocking I/O by storing the full content of HTTP messages in memory.
* The {@link HttpRequestExecutionHandler#handleResponse(HttpResponse, HttpContext)}
* method will fire only when the entire message content has been read into a
- * in-memory buffer. Please note that request execution / reponse processing
- * take place the main I/O thread and therefore {@link HttpRequestExecutionHandler}
- * methods should not block indefinitely.
- * <p/>
- * When using this protocol handelr {@link HttpEntity}'s content can be
- * generated / consumed using standard {@link InputStream} / {@link OutputStream}
+ * in-memory buffer. Please note that request execution / response processing
+ * take place the main I/O thread and therefore
+ * {@link HttpRequestExecutionHandler} methods should not block indefinitely.
+ * <p>
+ * When using this protocol handler {@link HttpEntity}'s content can be
+ * generated / consumed using standard {@link InputStream}/{@link OutputStream}
* classes.
- * <p/>
+ * <p>
* IMPORTANT: This protocol handler should be used only when dealing with HTTP
* messages that are known to be limited in length.
*
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpServiceHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpServiceHandler.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpServiceHandler.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/BufferingHttpServiceHandler.java Mon Jan 12 11:55:23 2009
@@ -65,11 +65,11 @@
* an in-memory buffer. Please note that request processing take place the
* main I/O thread and therefore individual HTTP request handlers should not
* block indefinitely.
- * <p/>
- * When using this protocol handelr {@link HttpEntity}'s content can be
- * generated / consumed using standard {@link InputStream} / {@link OutputStream}
+ * <p>
+ * When using this protocol handler {@link HttpEntity}'s content can be
+ * generated / consumed using standard {@link InputStream}/{@link OutputStream}
* classes.
- * <p/>
+ * <p>
* IMPORTANT: This protocol handler should be used only when dealing with HTTP
* messages that are known to be limited in length.
*
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/EventListener.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/EventListener.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/EventListener.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/EventListener.java Mon Jan 12 11:55:23 2009
@@ -37,21 +37,49 @@
import org.apache.http.nio.NHttpConnection;
/**
- * Event listener used by HTTP protocol layer to report fatal
- * exceptions and events that may need to be logged.
+ * Event listener used by the HTTP protocol layer to report fatal exceptions
+ * and events that may need to be logged using a logging toolkit.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*/
public interface EventListener {
+ /**
+ * Triggered when an I/O error caused a connection to be terminated.
+ *
+ * @param ex the I/O exception.
+ * @param conn the connection.
+ */
void fatalIOException(IOException ex, NHttpConnection conn);
+ /**
+ * Triggered when an HTTP protocol error caused a connection to be
+ * terminated.
+ *
+ * @param ex the protocol exception.
+ * @param conn the connection.
+ */
void fatalProtocolException(HttpException ex, NHttpConnection conn);
+ /**
+ * Triggered when a new connection has been established.
+ *
+ * @param conn the connection.
+ */
void connectionOpen(NHttpConnection conn);
+ /**
+ * Triggered when a connection has been terminated.
+ *
+ * @param conn the connection.
+ */
void connectionClosed(NHttpConnection conn);
+ /**
+ * Triggered when a connection has timed out.
+ *
+ * @param conn the connection.
+ */
void connectionTimeout(NHttpConnection conn);
}
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/HttpRequestExecutionHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/HttpRequestExecutionHandler.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/HttpRequestExecutionHandler.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/HttpRequestExecutionHandler.java Mon Jan 12 11:55:23 2009
@@ -55,7 +55,7 @@
* <p>The attachment object is the same object which was passed
* to the connecting I/O reactor when the connection request was
* made. The attachment may optionally contain some state information
- * required in order to correctly initalize the HTTP context.
+ * required in order to correctly initialize the HTTP context.
*
* @see ConnectingIOReactor#connect
*
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandler.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandler.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandler.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandler.java Mon Jan 12 11:55:23 2009
@@ -40,12 +40,61 @@
import org.apache.http.nio.entity.ConsumingNHttpEntity;
import org.apache.http.protocol.HttpContext;
+/**
+ * NHttpRequestHandler represents a routine for asynchronous processing of
+ * a specific group of non-blocking HTTP requests. Protocol handlers are
+ * designed to take care of protocol specific aspects, whereas individual
+ * request handlers are expected to take care of application specific HTTP
+ * processing. The main purpose of a request handler is to generate a response
+ * object with a content entity to be sent back to the client in response to
+ * the given request
+ *
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
+ *
+ * @since 4.0
+ */
public interface NHttpRequestHandler {
+ /**
+ * Triggered when a request is received with an entity. This method should
+ * return a {@link ConsumingNHttpEntity} that will be used to consume the
+ * entity. <code>null</code> is a valid response value, and will indicate
+ * that the entity should be silently ignored.
+ * <p>
+ * After the entity is fully consumed,
+ * {@link #handle(HttpRequest, HttpResponse, NHttpResponseTrigger, HttpContext)}
+ * is called to notify a full request & entity are ready to be processed.
+ *
+ * @param request the entity enclosing request.
+ * @param context the execution context.
+ * @return non-blocking HTTP entity.
+ * @throws IOException in case of an I/O error.
+ * @throws HttpException in case of HTTP protocol violation or a processing
+ * problem.
+ */
ConsumingNHttpEntity entityRequest(HttpEntityEnclosingRequest request,
HttpContext context)
throws HttpException, IOException;
+ /**
+ * Initiates processing of the request. This method does not have to submit
+ * a response immediately. It can defer transmission of the HTTP response
+ * back to the client without blocking the I/O thread by delegating the
+ * process of handling the HTTP request to a worker thread. The worker
+ * thread in its turn can use the instance of {@link NHttpResponseTrigger}
+ * passed as a parameter to submit a response as at a later point of time
+ * once content of the response becomes available.
+ *
+ * @param request the HTTP request.
+ * @param response the HTTP response.
+ * @param trigger the response trigger.
+ * @param context the HTTP execution context.
+ * @throws IOException in case of an I/O error.
+ * @throws HttpException in case of HTTP protocol violation or a processing
+ * problem.
+ */
void handle(HttpRequest request, HttpResponse response,
NHttpResponseTrigger trigger, HttpContext context)
throws HttpException, IOException;
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerRegistry.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerRegistry.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerRegistry.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerRegistry.java Mon Jan 12 11:55:23 2009
@@ -1,7 +1,7 @@
/*
- * $HeadURL:$
- * $Revision:$
- * $Date:$
+ * $HeadURL$
+ * $Revision$
+ * $Date$
*
* ====================================================================
* Licensed to the Apache Software Foundation (ASF) under one
@@ -37,14 +37,20 @@
/**
* Maintains a map of HTTP request handlers keyed by a request URI pattern.
- * {@link NHttpRequestHandler} instances can be looked up by request URI
- * using the {@link NHttpRequestHandlerResolver} interface.<br/>
+ * <br>
* Patterns may have three formats:
* <ul>
* <li><code>*</code></li>
* <li><code>*<uri></code></li>
* <li><code><uri>*</code></li>
* </ul>
+ * <br>
+ * This class can be used to resolve an instance of
+ * {@link NHttpRequestHandler} matching a particular request URI. Usually the
+ * resolved request handler will be used to process the request with the
+ * specified request URI.
+ *
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
* @version $Revision$
*/
@@ -56,14 +62,30 @@
matcher = new UriPatternMatcher();
}
+ /**
+ * Registers the given {@link NHttpRequestHandler} as a handler for URIs
+ * matching the given pattern.
+ *
+ * @param pattern the pattern to register the handler for.
+ * @param handler the handler.
+ */
public void register(final String pattern, final NHttpRequestHandler handler) {
matcher.register(pattern, handler);
}
+ /**
+ * Removes registered handler, if exists, for the given pattern.
+ *
+ * @param pattern the pattern to unregister the handler for.
+ */
public void unregister(final String pattern) {
matcher.unregister(pattern);
}
+ /**
+ * Sets handlers from the given map.
+ * @param map the map containing handlers keyed by their URI patterns.
+ */
public void setHandlers(final Map<String, ? extends NHttpRequestHandler> map) {
matcher.setHandlers(map);
}
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerResolver.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerResolver.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerResolver.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpRequestHandlerResolver.java Mon Jan 12 11:55:23 2009
@@ -1,7 +1,7 @@
/*
- * $HeadURL:$
- * $Revision:$
- * $Date:$
+ * $HeadURL$
+ * $Revision$
+ * $Date$
*
* ====================================================================
* Licensed to the Apache Software Foundation (ASF) under one
@@ -32,15 +32,24 @@
package org.apache.http.nio.protocol;
/**
- * Interface to be implemented by objects that can resolve
- * {@link NHttpRequestHandler} instances by request URI.
+ * HttpRequestHandlerResolver can be used to resolve an instance of
+ * {@link NHttpRequestHandler} matching a particular request URI. Usually the
+ * resolved request handler will be used to process the request with the
+ * specified request URI.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
- * @version $Revision:$
+ * @version $Revision$
*/
public interface NHttpRequestHandlerResolver {
+ /**
+ * Looks up a handler matching the given request URI.
+ *
+ * @param requestURI the request URI
+ * @return HTTP request handler or <code>null</code> if no match
+ * is found.
+ */
NHttpRequestHandler lookup(String requestURI);
}
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpResponseTrigger.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpResponseTrigger.java?rev=733879&r1=733878&r2=733879&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpResponseTrigger.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/NHttpResponseTrigger.java Mon Jan 12 11:55:23 2009
@@ -40,12 +40,12 @@
* Callback interface to submit HTTP responses asynchronously.
* <p/>
* The {@link NHttpRequestHandler#handle(org.apache.http.HttpRequest, HttpResponse, NHttpResponseTrigger, org.apache.http.protocol.HttpContext)}
- * method does not have to submit a response immediately. I can defer
- * transmittion of the HTTP response back to the client without blocking the
+ * method does not have to submit a response immediately. It can defer
+ * transmission of the HTTP response back to the client without blocking the
* I/O thread by delegating the process of handling the HTTP request to a worker
* thread. The worker thread in its turn can use the instance of
* {@link NHttpResponseTrigger} passed as a parameter to submit a response as at
- * a later point of time once the response becomes avaialble.
+ * a later point of time once the response becomes available.
*/
public interface NHttpResponseTrigger {
Added: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/package.html?rev=733879&view=auto
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/package.html (added)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/protocol/package.html Mon Jan 12 11:55:23 2009
@@ -0,0 +1,40 @@
+<html>
+<head>
+<!--
+/*
+ * $HeadURL: http://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk/module-main/src/main/java/org/apache/http/protocol/package.html $
+ * $Revision: 496070 $
+ * $Date: 2007-01-14 13:18:34 +0100 (Sun, 14 Jan 2007) $
+ *
+ * ====================================================================
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you 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.
+ * ====================================================================
+ *
+ * This software consists of voluntary contributions made by many
+ * individuals on behalf of the Apache Software Foundation. For more
+ * information on the Apache Software Foundation, please see
+ * <http://www.apache.org/>.
+ *
+ */
+-->
+</head>
+<body>
+Non-blocking HTTP protocol execution framework. This package contains protocol
+handler implementations based on NIO model.
+</body>
+</html>