Permalink
Browse files

Updated NOTICE and javadocs

git-svn-id: https://svn.apache.org/repos/asf/httpcomponents/httpcore/trunk@1232896 13f79535-47bb-0310-9956-ffa450edef68
  • Loading branch information...
1 parent 2e171e5 commit 3d820befc7f6cbb86bc174ed91d43a54d8fff147 @ok2c ok2c committed Jan 18, 2012
View
@@ -1,5 +1,8 @@
Apache HttpComponents Core
-Copyright 2005-2011 The Apache Software Foundation
+Copyright 2005-2012 The Apache Software Foundation
This product includes software developed by
The Apache Software Foundation (http://www.apache.org/).
+
+This project contains annotations derived from JCIP-ANNOTATIONS
+Copyright (c) 2005 Brian Goetz and Tim Peierls. See http://www.jcip.net
@@ -0,0 +1,36 @@
+<html>
+<head>
+<!--
+/*
+ * ====================================================================
+ * 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>
+Basic implementations for interfaces in
+{@link org.apache.http.nio.pool org.apache.http.nio.pool}.
+</body>
+</html>
@@ -0,0 +1,35 @@
+<html>
+<head>
+<!--
+/*
+ * ====================================================================
+ * 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>
+Deprecated
+</body>
+</html>
@@ -30,19 +30,13 @@
-->
</head>
<body>
-Representations for non-blocking HTTP message entities.
+Common HTTP entity implementations with extensions for
+asynchronous (non-blocking) data transfer.
-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>
@@ -30,10 +30,9 @@
-->
</head>
<body>
-The core HTTP components based on non-blocking I/O model (HttpCore NIO).
+Core HTTP components based on the non-blocking I/O model.
<p/>
This layer defines interfaces for transferring HTTP messages over non-blocking
-HTTP connections and protocol handlers for processing HTTP messages
-asynchronously.
+HTTP connections and event handlers for processing HTTP messages asynchronously.
</body>
</html>
@@ -0,0 +1,35 @@
+<html>
+<head>
+<!--
+/*
+ * ====================================================================
+ * 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>
+Asynchronous (non-blocking) connection pool components.
+</body>
+</html>
@@ -30,7 +30,6 @@
-->
</head>
<body>
-Non-blocking HTTP protocol execution framework. This package contains protocol
-handler implementations based on NIO model.
+Asynchronous HTTP protocol handlers based on the non-blocking I/O model.
</body>
</html>
@@ -47,8 +47,19 @@
import java.nio.channels.SelectionKey;
/**
- * A decorator class intended to transparently extend an {@link IOSession}
- * with transport layer security capabilities based on the SSL/TLS protocol.
+ * <tt>SSLIOSession</tt> is a decorator class intended to transparently extend
+ * an {@link IOSession} with transport layer security capabilities based on
+ * the SSL/TLS protocol.
+ * <p/>
+ * The resultant instance of <tt>SSLIOSession</tt> must be added to the original
+ * I/O session as an attribute with the {@link #SESSION_KEY} key.
+ * <pre>
+ * SSLContext sslcontext = SSLContext.getInstance("SSL");
+ * sslcontext.init(null, null, null);
+ * SSLIOSession sslsession = new SSLIOSession(
+ * iosession, SSLMode.CLIENT, sslcontext, null);
+ * iosession.setAttribute(SSLIOSession.SESSION_KEY, sslsession);
+ * </pre>
*
* @since 4.2
*/
@@ -78,6 +89,14 @@
private volatile int status;
private volatile boolean initialized;
+ /**
+ * Creates new instance of <tt>SSLIOSession</tt> class.
+ *
+ * @param session I/O session to be decorated with the TLS/SSL capabilities.
+ * @param defaultMode default mode (client or server)
+ * @param sslContext SSL context to use for this I/O session.
+ * @param handler optional SSL setup handler. May be <code>null</code>.
+ */
public SSLIOSession(
final IOSession session,
final SSLMode defaultMode,
@@ -123,10 +142,24 @@ protected SSLSetupHandler getSSLSetupHandler() {
return this.handler;
}
+ /**
+ * Returns <code>true</code> is the session has been fully initialized,
+ * <code>false</code> otherwise.
+ */
public boolean isInitialized() {
return this.initialized;
}
+ /**
+ * Initializes the session in the given {@link SSLMode}. This method
+ * invokes the {@link SSLSetupHandler#initalize(SSLEngine)} callback
+ * if an instance of {@link SSLSetupHandler} was specified at
+ * the construction time.
+ *
+ * @param mode mode of operation (client or server).
+ * @throws SSLException in case of a SSL protocol exception.
+ * @throws IllegalStateException if the session has already been initialized.
+ */
public synchronized void initialize(final SSLMode mode) throws SSLException {
if (this.initialized) {
throw new IllegalStateException("SSL I/O session already initialized");
@@ -150,6 +183,15 @@ public synchronized void initialize(final SSLMode mode) throws SSLException {
doHandshake();
}
+ /**
+ * Initializes the session in the default operation mode. This method
+ * invokes the {@link SSLSetupHandler#initalize(SSLEngine)} callback
+ * if an instance of {@link SSLSetupHandler} was specified at
+ * the construction time.
+ *
+ * @throws SSLException in case of a SSL protocol exception.
+ * @throws IllegalStateException if the session has already been initialized.
+ */
public void initialize() throws SSLException {
initialize(this.defaultMode);
}
@@ -312,6 +354,12 @@ private boolean decryptData() throws SSLException {
return decrypted;
}
+ /**
+ * Reads encrypted data and returns whether the channel associated with
+ * this session has any decrypted inbound data available for reading.
+ *
+ * @throws IOException in case of an I/O error.
+ */
public synchronized boolean isAppInputReady() throws IOException {
int bytesRead = receiveEncryptedData();
if (bytesRead == -1) {
@@ -327,6 +375,9 @@ public synchronized boolean isAppInputReady() throws IOException {
}
/**
+ * Returns whether the channel associated with this session is ready to
+ * accept outbound unecrypted data for writing.
+ *
* @throws IOException - not thrown currently
*/
public synchronized boolean isAppOutputReady() throws IOException {
@@ -336,18 +387,39 @@ public synchronized boolean isAppOutputReady() throws IOException {
}
/**
+ * Executes inbound SSL transport operations.
+ *
* @throws IOException - not thrown currently
*/
public synchronized void inboundTransport() throws IOException {
updateEventMask();
}
+ /**
+ * Sends encrypted data and executes outbound SSL transport operations.
+ *
+ * @throws IOException in case of an I/O error.
+ */
public synchronized void outboundTransport() throws IOException {
sendEncryptedData();
doHandshake();
updateEventMask();
}
+ /**
+ * Returns whether the session will produce any more inbound data.
+ */
+ public synchronized boolean isInboundDone() {
+ return this.sslEngine.isInboundDone();
+ }
+
+ /**
+ * Returns whether the session will accept any more outbound data.
+ */
+ public synchronized boolean isOutboundDone() {
+ return this.sslEngine.isOutboundDone();
+ }
+
private synchronized int writePlain(final ByteBuffer src) throws SSLException {
if (src == null) {
throw new IllegalArgumentException("Byte buffer may not be null");
@@ -371,10 +443,7 @@ private synchronized int writePlain(final ByteBuffer src) throws SSLException {
}
}
- /**
- * @throws SSLException - not thrown currently
- */
- private synchronized int readPlain(final ByteBuffer dst) throws SSLException {
+ private synchronized int readPlain(final ByteBuffer dst) {
if (dst == null) {
throw new IllegalArgumentException("Byte buffer may not be null");
}
@@ -420,14 +489,6 @@ public boolean isClosed() {
return this.status >= CLOSING;
}
- public synchronized boolean isInboundDone() {
- return this.sslEngine.isInboundDone();
- }
-
- public synchronized boolean isOutboundDone() {
- return this.sslEngine.isOutboundDone();
- }
-
public ByteChannel channel() {
return this.channel;
}
@@ -0,0 +1,35 @@
+<html>
+<head>
+<!--
+/*
+ * ====================================================================
+ * 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 TLS/SSL session implementation.
+</body>
+</html>
Oops, something went wrong.

0 comments on commit 3d820be

Please sign in to comment.