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/11 23:14:10 UTC
svn commit: r733525 - in
/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio:
entity/ util/
Author: olegk
Date: Sun Jan 11 14:14:10 2009
New Revision: 733525
URL: http://svn.apache.org/viewvc?rev=733525&view=rev
Log:
Javadoc updates
Added:
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/package.html
Modified:
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/util/BufferInfo.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ByteBufferAllocator.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ContentInputBuffer.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ContentOutputBuffer.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/DirectByteBufferAllocator.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ExpandableBuffer.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/HeapByteBufferAllocator.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SharedInputBuffer.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SharedOutputBuffer.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SimpleInputBuffer.java
httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SimpleOutputBuffer.java
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=733525&r1=733524&r2=733525&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 Sun Jan 11 14:14:10 2009
@@ -55,7 +55,6 @@
@Override
public void flush() throws IOException {
- this.buffer.flush();
}
@Override
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/BufferInfo.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/BufferInfo.java?rev=733525&r1=733524&r2=733525&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/BufferInfo.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/BufferInfo.java Sun Jan 11 14:14:10 2009
@@ -33,10 +33,14 @@
/**
* Basic buffer properties.
+ * <p>
+ * This interface should be eliminated in the next major release and its
+ * methods added to {@link org.apache.http.nio.reactor.SessionOutputBuffer}
+ * and {@link org.apache.http.nio.reactor.SessionInputBuffer} interfaces.
*
* @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
*
- * @since 4.0-beta2
+ * @version $Revision$
*/
public interface BufferInfo {
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ByteBufferAllocator.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ByteBufferAllocator.java?rev=733525&r1=733524&r2=733525&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ByteBufferAllocator.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ByteBufferAllocator.java Sun Jan 11 14:14:10 2009
@@ -33,8 +33,17 @@
import java.nio.ByteBuffer;
+/**
+ * Abstract interface to allocate {@link ByteBuffer} instances.
+ */
public interface ByteBufferAllocator {
+ /**
+ * Allocates {@link ByteBuffer} of the given size.
+ *
+ * @param size the size of the buffer.
+ * @return byte buffer.
+ */
ByteBuffer allocate(int size);
}
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ContentInputBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ContentInputBuffer.java?rev=733525&r1=733524&r2=733525&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ContentInputBuffer.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ContentInputBuffer.java Sun Jan 11 14:14:10 2009
@@ -35,14 +35,61 @@
import org.apache.http.nio.ContentDecoder;
+/**
+ * Buffer for storing content streamed out from a {@link ContentDecoder}.
+ *
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
+ */
public interface ContentInputBuffer {
+ /**
+ * Reads content from the given {@link ContentDecoder} and stores it in
+ * this buffer.
+ *
+ * @param decoder the content decoder.
+ * @return number of bytes read.
+ * @throws IOException in case of an I/O error.
+ */
int consumeContent(ContentDecoder decoder) throws IOException;
+ /**
+ * Resets the buffer by clearing its state and stored content.
+ */
void reset();
+ /**
+ * Reads up to <code>len</code> bytes of data from this buffer into
+ * an array of bytes. The exact number of bytes read depends how many bytes
+ * are stored in the buffer.
+ *
+ * <p> If <code>off</code> is negative, or <code>len</code> is negative, or
+ * <code>off+len</code> is greater than the length of the array
+ * <code>b</code>, this method can throw a runtime exception. The exact type
+ * of runtime exception thrown by this method depends on implementation.
+ * This method returns <code>-1</code> if the end of content stream has been
+ * reached.
+ *
+ * @param b the buffer into which the data is read.
+ * @param off the start offset in array <code>b</code>
+ * at which the data is written.
+ * @param len the maximum number of bytes to read.
+ * @return the total number of bytes read into the buffer, or
+ * <code>-1</code> if there is no more data because the end of
+ * the stream has been reached.
+ * @exception IOException if an I/O error occurs.
+ */
int read(byte[] b, int off, int len) throws IOException;
+ /**
+ * Reads one byte from this buffer. If the buffer is empty this method can
+ * throw a runtime exception. The exact type of runtime exception thrown
+ * by this method depends on implementation. This method returns
+ * <code>-1</code> if the end of content stream has been reached.
+ *
+ * @return one byte
+ */
int read() throws IOException;
}
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ContentOutputBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ContentOutputBuffer.java?rev=733525&r1=733524&r2=733525&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ContentOutputBuffer.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ContentOutputBuffer.java Sun Jan 11 14:14:10 2009
@@ -35,18 +35,60 @@
import org.apache.http.nio.ContentEncoder;
+/**
+ * Buffer for storing content to be streamed out to a {@link ContentEncoder}.
+ *
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
+ */
public interface ContentOutputBuffer {
+ /**
+ * Writes content from this buffer to the given {@link ContentEncoder}.
+ *
+ * @param encoder content encoder.
+ * @return number of bytes written.
+ * @throws IOException in case of an I/O error.
+ */
int produceContent(ContentEncoder encoder) throws IOException;
+ /**
+ * Resets the buffer by clearing its state and stored content.
+ */
void reset();
- public void flush() throws IOException;
+ @Deprecated
+ void flush() throws IOException;
+ /**
+ * Writes <code>len</code> bytes from the specified byte array
+ * starting at offset <code>off</code> to this buffer.
+ * <p>
+ * If <code>off</code> is negative, or <code>len</code> is negative, or
+ * <code>off+len</code> is greater than the length of the array
+ * <code>b</code>, this method can throw a runtime exception. The exact type
+ * of runtime exception thrown by this method depends on implementation.
+ *
+ * @param b the data.
+ * @param off the start offset in the data.
+ * @param len the number of bytes to write.
+ * @exception IOException if an I/O error occurs.
+ */
void write(byte[] b, int off, int len) throws IOException;
+ /**
+ * Writes the specified byte to this buffer.
+ *
+ * @param b the <code>byte</code>.
+ * @exception IOException if an I/O error occurs.
+ */
void write(int b) throws IOException;
+ /**
+ * Indicates the content has been fully written.
+ * @exception IOException if an I/O error occurs.
+ */
void writeCompleted() throws IOException;
}
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/DirectByteBufferAllocator.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/DirectByteBufferAllocator.java?rev=733525&r1=733524&r2=733525&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/DirectByteBufferAllocator.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/DirectByteBufferAllocator.java Sun Jan 11 14:14:10 2009
@@ -33,6 +33,10 @@
import java.nio.ByteBuffer;
+/**
+ * Allocates {@link ByteBuffer} instances using
+ * {@link ByteBuffer#allocateDirect(int)}.
+ */
public class DirectByteBufferAllocator implements ByteBufferAllocator {
public ByteBuffer allocate(int size) {
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ExpandableBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ExpandableBuffer.java?rev=733525&r1=733524&r2=733525&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ExpandableBuffer.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/ExpandableBuffer.java Sun Jan 11 14:14:10 2009
@@ -33,6 +33,15 @@
import java.nio.ByteBuffer;
+/**
+ * A buffer that expand its capacity on demand using {@link ByteBufferAllocator}
+ * interface. Internally, this class is backed by an instance of
+ * {@link ByteBuffer}.
+ *
+ * @author <a href="mailto:oleg at ural.ru">Oleg Kalnichevski</a>
+ *
+ * @version $Revision$
+ */
public class ExpandableBuffer implements BufferInfo {
public final static int INPUT_MODE = 0;
@@ -42,6 +51,12 @@
protected ByteBuffer buffer = null;
private final ByteBufferAllocator allocator;
+ /**
+ * Allocates buffer of the given size using the given allocator.
+ *
+ * @param buffersize the buffer size.
+ * @param allocator allocator to be used to allocate {@link ByteBuffer}s.
+ */
public ExpandableBuffer(int buffersize, final ByteBufferAllocator allocator) {
super();
if (allocator == null) {
@@ -52,10 +67,22 @@
this.mode = INPUT_MODE;
}
+ /**
+ * Returns the current mode:
+ * <p>
+ * {@link #INPUT_MODE}: the buffer is in the input mode.
+ * <p>
+ * {@link #OUTPUT_MODE}: the buffer is in the output mode.
+ *
+ * @return current input/output mode.
+ */
protected int getMode() {
return this.mode;
}
-
+
+ /**
+ * Sets output mode. The buffer can now be read from.
+ */
protected void setOutputMode() {
if (this.mode != OUTPUT_MODE) {
this.buffer.flip();
@@ -63,6 +90,9 @@
}
}
+ /**
+ * Sets input mode. The buffer can now be written into.
+ */
protected void setInputMode() {
if (this.mode != INPUT_MODE) {
if (this.buffer.hasRemaining()) {
@@ -81,6 +111,9 @@
this.buffer.put(oldbuffer);
}
+ /**
+ * Expands buffer's capacity.
+ */
protected void expand() {
int newcapacity = (this.buffer.capacity() + 1) << 1;
if (newcapacity < 0) {
@@ -89,31 +122,60 @@
expandCapacity(newcapacity);
}
+ /**
+ * Ensures the buffer can accommodate the required capacity.
+ *
+ * @param requiredCapacity
+ */
protected void ensureCapacity(int requiredCapacity) {
if (requiredCapacity > this.buffer.capacity()) {
expandCapacity(requiredCapacity);
}
}
+ /**
+ * Returns the total capacity of this buffer.
+ *
+ * @return total capacity.
+ */
public int capacity() {
return this.buffer.capacity();
}
+ /**
+ * Determines if the buffer contains data.
+ *
+ * @return <code>true</code> if there is data in the buffer,
+ * <code>false</code> otherwise.
+ */
public boolean hasData() {
setOutputMode();
return this.buffer.hasRemaining();
}
+ /**
+ * Returns the length of this buffer.
+ *
+ * @return buffer length.
+ */
public int length() {
setOutputMode();
return this.buffer.remaining();
}
+ /**
+ * Returns available capacity of this buffer.
+ *
+ * @return buffer length.
+ */
public int available() {
setInputMode();
return this.buffer.remaining();
}
+ /**
+ * Clears buffer.
+ */
protected void clear() {
this.buffer.clear();
this.mode = INPUT_MODE;
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/HeapByteBufferAllocator.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/HeapByteBufferAllocator.java?rev=733525&r1=733524&r2=733525&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/HeapByteBufferAllocator.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/HeapByteBufferAllocator.java Sun Jan 11 14:14:10 2009
@@ -33,6 +33,10 @@
import java.nio.ByteBuffer;
+/**
+ * Allocates {@link ByteBuffer} instances using
+ * {@link ByteBuffer#allocate(int)}.
+ */
public class HeapByteBufferAllocator implements ByteBufferAllocator {
public ByteBuffer allocate(int size) {
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SharedInputBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SharedInputBuffer.java?rev=733525&r1=733524&r2=733525&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SharedInputBuffer.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SharedInputBuffer.java Sun Jan 11 14:14:10 2009
@@ -36,6 +36,11 @@
import org.apache.http.nio.ContentDecoder;
import org.apache.http.nio.IOControl;
+/**
+ * Implementation of the {@link ContentInputBuffer} interface that can be
+ * shared by multiple threads, usually the I/O dispatch of an I/O reactor and
+ * a worker tread. This class is not threading safe.
+ */
public class SharedInputBuffer extends ExpandableBuffer implements ContentInputBuffer {
private final IOControl ioctrl;
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SharedOutputBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SharedOutputBuffer.java?rev=733525&r1=733524&r2=733525&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SharedOutputBuffer.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SharedOutputBuffer.java Sun Jan 11 14:14:10 2009
@@ -36,6 +36,11 @@
import org.apache.http.nio.ContentEncoder;
import org.apache.http.nio.IOControl;
+/**
+ * Implementation of the {@link ContentOutputBuffer} interface that can be
+ * shared by multiple threads, usually the I/O dispatch of an I/O reactor and
+ * a worker tread. This class is not threading safe.
+ */
public class SharedOutputBuffer extends ExpandableBuffer implements ContentOutputBuffer {
private final IOControl ioctrl;
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SimpleInputBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SimpleInputBuffer.java?rev=733525&r1=733524&r2=733525&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SimpleInputBuffer.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SimpleInputBuffer.java Sun Jan 11 14:14:10 2009
@@ -34,6 +34,10 @@
import org.apache.http.nio.ContentDecoder;
+/**
+ * Simple implementation of the {@link ContentInputBuffer} interface. This class
+ * is not threading safe.
+ */
public class SimpleInputBuffer extends ExpandableBuffer implements ContentInputBuffer {
private boolean endOfStream = false;
Modified: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SimpleOutputBuffer.java
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SimpleOutputBuffer.java?rev=733525&r1=733524&r2=733525&view=diff
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SimpleOutputBuffer.java (original)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/SimpleOutputBuffer.java Sun Jan 11 14:14:10 2009
@@ -34,6 +34,10 @@
import org.apache.http.nio.ContentEncoder;
+/**
+ * Simple implementation of the {@link ContentOutputBuffer} interface.
+ * This class is not threading safe.
+ */
public class SimpleOutputBuffer extends ExpandableBuffer implements ContentOutputBuffer {
private boolean endOfStream;
Added: httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/package.html
URL: http://svn.apache.org/viewvc/httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/package.html?rev=733525&view=auto
==============================================================================
--- httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/package.html (added)
+++ httpcomponents/httpcore/trunk/module-nio/src/main/java/org/apache/http/nio/util/package.html Sun Jan 11 14:14:10 2009
@@ -0,0 +1,40 @@
+<html>
+<head>
+<!--
+/*
+ * $HeadURL: $
+ * $Revision: $
+ * $Date: $
+ *
+ * ====================================================================
+ * 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>
+Various buffering primitives intended to facilitate content streaming for
+non-blocking HTTP connections.
+</body>
+</html>