Initial work towards OPENDJ-1195: Realign the SDK developer guide with the ...

Matthew Swift

27.13.2013 4d2b164e9ae0b74b63903e9e24ff1b0184fde771

Initial work towards OPENDJ-1195: Realign the SDK developer guide with the SDK trunk once the new Maven module and package layout has been validated

* move all classes to public org.* package so that they get Javadoc, except for GrizzlyTransportProvider.

 opendj-grizzly/src/main/java/com/forgerock/opendj/grizzly/GrizzlyTransportProvider.java

@@ -28,6 +28,8 @@
import java.io.IOException;
import java.net.SocketAddress;

import org.forgerock.opendj.grizzly.GrizzlyLDAPConnectionFactory;
import org.forgerock.opendj.grizzly.GrizzlyLDAPListener;
import org.forgerock.opendj.ldap.LDAPClientContext;
import org.forgerock.opendj.ldap.LDAPListenerOptions;
import org.forgerock.opendj.ldap.LDAPOptions;
@@ -37,24 +39,7 @@
import org.forgerock.opendj.ldap.spi.TransportProvider;

/**
 * Provides an implementation of a transport provider using Grizzly as
 * transport. This provider is named "Grizzly".
 * <p>
 * To be used, this implementation must be declared in the
 * provider-configuration file
 * {@code META-INF/services/org.forgerock.opendj.ldap.spi.TransportProvider}
 * with this single line:
 *
 * <pre>
 * com.forgerock.opendj.ldap.GrizzlyTransportProvider
 * </pre>.
 * <p>
 * To require that this implementation is used, you must set the transport
 * provider to "Grizzly" using {@code LDAPOptions#setTransportProvider()}
 * method if requesting a {@code LDAPConnectionFactory} or
 * {@code LDAPListenerOptions#setTransportProvider()} method if requesting a
 * {@code LDAPListener}. Otherwise there is no guarantee that this
 * implementation will be used.
 * Grizzly transport provider implementation.
 */
public class GrizzlyTransportProvider implements TransportProvider {


 opendj-grizzly/src/main/java/org/forgerock/opendj/grizzly/ASN1BufferReader.java

File was renamed from opendj-grizzly/src/main/java/com/forgerock/opendj/grizzly/ASN1BufferReader.java
@@ -25,10 +25,17 @@
 *      Portions copyright 2012-2013 ForgeRock AS.
 */

package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import static com.forgerock.opendj.ldap.CoreMessages.*;
import static com.forgerock.opendj.util.StaticUtils.*;
import static com.forgerock.opendj.ldap.CoreMessages.ERR_ASN1_BOOLEAN_INVALID_LENGTH;
import static com.forgerock.opendj.ldap.CoreMessages.ERR_ASN1_INTEGER_INVALID_LENGTH;
import static com.forgerock.opendj.ldap.CoreMessages.ERR_ASN1_INVALID_NUM_LENGTH_BYTES;
import static com.forgerock.opendj.ldap.CoreMessages.ERR_ASN1_NULL_INVALID_LENGTH;
import static com.forgerock.opendj.ldap.CoreMessages.ERR_ASN1_SEQUENCE_READ_NOT_STARTED;
import static com.forgerock.opendj.ldap.CoreMessages.ERR_ASN1_TRUNCATED_LENGTH_BYTE;
import static com.forgerock.opendj.ldap.CoreMessages.ERR_LDAP_CLIENT_DECODE_MAX_REQUEST_SIZE_EXCEEDED;
import static com.forgerock.opendj.util.StaticUtils.IO_LOG;
import static com.forgerock.opendj.util.StaticUtils.byteToHex;

import java.io.IOException;


 opendj-grizzly/src/main/java/org/forgerock/opendj/grizzly/ASN1BufferWriter.java

File was renamed from opendj-grizzly/src/main/java/com/forgerock/opendj/grizzly/ASN1BufferWriter.java
@@ -24,7 +24,7 @@
 *      Copyright 2010 Sun Microsystems, Inc.
 *      Portions copyright 2012-2013 ForgeRock AS.
 */
package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import static com.forgerock.opendj.ldap.CoreMessages.ERR_ASN1_SEQUENCE_WRITE_NOT_STARTED;
import static com.forgerock.opendj.util.StaticUtils.IO_LOG;

 opendj-grizzly/src/main/java/org/forgerock/opendj/grizzly/ConnectionSecurityLayerFilter.java

File was renamed from opendj-grizzly/src/main/java/com/forgerock/opendj/grizzly/ConnectionSecurityLayerFilter.java
@@ -25,7 +25,7 @@
 *      Portions copyright 2012 ForgeRock AS.
 */

package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import org.forgerock.opendj.ldap.ConnectionSecurityLayer;
import org.forgerock.opendj.ldap.ErrorResultException;

 opendj-grizzly/src/main/java/org/forgerock/opendj/grizzly/DefaultTCPNIOTransport.java

File was renamed from opendj-grizzly/src/main/java/com/forgerock/opendj/grizzly/DefaultTCPNIOTransport.java
@@ -25,11 +25,12 @@
 *      Portions copyright 2011-2013 ForgeRock AS
 */

package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import static com.forgerock.opendj.util.StaticUtils.DEFAULT_LOG;

import java.io.IOException;

import org.glassfish.grizzly.nio.transport.TCPNIOTransport;
import org.glassfish.grizzly.nio.transport.TCPNIOTransportBuilder;
import org.glassfish.grizzly.strategies.SameThreadIOStrategy;

 opendj-grizzly/src/main/java/org/forgerock/opendj/grizzly/GrizzlyLDAPConnection.java

File was renamed from opendj-grizzly/src/main/java/com/forgerock/opendj/grizzly/GrizzlyLDAPConnection.java
@@ -25,11 +25,10 @@
 *      Portions Copyright 2011-2013 ForgeRock AS
 */

package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import static com.forgerock.opendj.util.StaticUtils.*;

import static org.forgerock.opendj.ldap.ErrorResultException.*;
import static com.forgerock.opendj.util.StaticUtils.DEFAULT_LOG;
import static org.forgerock.opendj.ldap.ErrorResultException.newErrorResult;

import java.io.IOException;
import java.net.InetSocketAddress;

 opendj-grizzly/src/main/java/org/forgerock/opendj/grizzly/GrizzlyLDAPConnectionFactory.java

File was renamed from opendj-grizzly/src/main/java/com/forgerock/opendj/grizzly/GrizzlyLDAPConnectionFactory.java
@@ -25,10 +25,10 @@
 *      Portions copyright 2011-2013 ForgeRock AS
 */

package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import static com.forgerock.opendj.grizzly.DefaultTCPNIOTransport.DEFAULT_TRANSPORT;
import static org.forgerock.opendj.ldap.ErrorResultException.*;
import static org.forgerock.opendj.grizzly.DefaultTCPNIOTransport.DEFAULT_TRANSPORT;
import static org.forgerock.opendj.ldap.ErrorResultException.newErrorResult;
import static org.forgerock.opendj.ldap.TimeoutChecker.TIMEOUT_CHECKER;

import java.io.IOException;

 opendj-grizzly/src/main/java/org/forgerock/opendj/grizzly/GrizzlyLDAPListener.java

File was renamed from opendj-grizzly/src/main/java/com/forgerock/opendj/grizzly/GrizzlyLDAPListener.java
@@ -25,10 +25,10 @@
 *      Portions copyright 2011-2013 ForgeRock AS
 */

package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import static com.forgerock.opendj.grizzly.DefaultTCPNIOTransport.DEFAULT_TRANSPORT;
import static com.forgerock.opendj.util.StaticUtils.DEFAULT_LOG;
import static org.forgerock.opendj.grizzly.DefaultTCPNIOTransport.DEFAULT_TRANSPORT;

import java.io.IOException;
import java.net.SocketAddress;

 opendj-grizzly/src/main/java/org/forgerock/opendj/grizzly/GrizzlyUtils.java

File was renamed from opendj-grizzly/src/main/java/com/forgerock/opendj/grizzly/GrizzlyUtils.java
@@ -23,7 +23,7 @@
 *
 *      Copyright 2013 ForgeRock AS.
 */
package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import org.forgerock.opendj.io.LDAP;
import org.forgerock.opendj.io.LDAPReader;

 opendj-grizzly/src/main/java/org/forgerock/opendj/grizzly/LDAPBaseFilter.java

File was renamed from opendj-grizzly/src/main/java/com/forgerock/opendj/grizzly/LDAPBaseFilter.java
@@ -23,7 +23,7 @@
 *
 *      Copyright 2013 ForgeRock AS.
 */
package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import java.io.IOException;

@@ -41,18 +41,18 @@
 * Provides a common {@code handleRead()} method for both client and server
 * filters.
 */
public abstract class LDAPBaseFilter extends BaseFilter {
abstract class LDAPBaseFilter extends BaseFilter {

    /**
     * The maximum BER element size, or <code>0</code> to indicate that there is
     * no limit.
     */
    protected final int maxASN1ElementSize;
    final int maxASN1ElementSize;

    /**
     * Allow to control how to decode requests and responses.
     */
    protected final DecodeOptions decodeOptions;
    final DecodeOptions decodeOptions;

    /**
     * Creates a filter with provided decode options and max size of
@@ -64,7 +64,7 @@
     *            The maximum BER element size, or <code>0</code> to indicate
     *            that there is no limit.
     */
    protected LDAPBaseFilter(final DecodeOptions options, final int maxASN1ElementSize) {
    LDAPBaseFilter(final DecodeOptions options, final int maxASN1ElementSize) {
        this.decodeOptions = options;
        this.maxASN1ElementSize = maxASN1ElementSize;
    }
@@ -100,13 +100,13 @@
     * @param e
     *            exception occuring while reading
     */
    protected abstract void handleReadException(FilterChainContext ctx, IOException e);
    abstract void handleReadException(FilterChainContext ctx, IOException e);

    /**
     * Interface for the {@code LDAPMessageHandler} used in the filter, that
     * must be able to retrieve a Grizzly reader.
     */
    protected interface LDAPBaseHandler extends LDAPMessageHandler {
    interface LDAPBaseHandler extends LDAPMessageHandler {
        /**
         * Returns the LDAP reader for this handler.
         * @return the reader
@@ -126,6 +126,6 @@
     * @return the response handler associated to the connection, which can be a
     *         new one if no handler have been created yet
     */
    protected abstract LDAPBaseHandler getLDAPHandler(final FilterChainContext ctx);
    abstract LDAPBaseHandler getLDAPHandler(final FilterChainContext ctx);

}

 opendj-grizzly/src/main/java/org/forgerock/opendj/grizzly/LDAPClientFilter.java

File was renamed from opendj-grizzly/src/main/java/com/forgerock/opendj/grizzly/LDAPClientFilter.java
@@ -25,7 +25,7 @@
 *      Portions copyright 2012-2013 ForgeRock AS.
 */

package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import java.io.EOFException;
import java.io.IOException;
@@ -92,7 +92,7 @@
         * @param reader
         *            LDAP reader to use for reading incoming messages
         */
        public ClientResponseHandler(LDAPReader<ASN1BufferReader> reader) {
        ClientResponseHandler(LDAPReader<ASN1BufferReader> reader) {
            this.reader = reader;
        }

@@ -504,7 +504,7 @@
    }

    @Override
    protected final void handleReadException(FilterChainContext ctx, IOException e) {
    final void handleReadException(FilterChainContext ctx, IOException e) {
        final GrizzlyLDAPConnection ldapConnection = LDAP_CONNECTION_ATTR.get(ctx.getConnection());
        final Result errorResult =
                Responses.newResult(ResultCode.CLIENT_SIDE_DECODING_ERROR).setCause(e)
@@ -525,7 +525,7 @@
     *         new one if no handler have been created yet
     */
    @Override
    protected final LDAPBaseHandler getLDAPHandler(final FilterChainContext ctx) {
    final LDAPBaseHandler getLDAPHandler(final FilterChainContext ctx) {
        Connection<?> connection = ctx.getConnection();
        ClientResponseHandler handler = RESPONSE_HANDLER_ATTR.get(connection);
        if (handler == null) {

 opendj-grizzly/src/main/java/org/forgerock/opendj/grizzly/LDAPServerFilter.java

File was renamed from opendj-grizzly/src/main/java/com/forgerock/opendj/grizzly/LDAPServerFilter.java
@@ -25,7 +25,7 @@
 *      Portions copyright 2012-2013 ForgeRock AS.
 */

package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import java.io.IOException;
import java.net.InetSocketAddress;
@@ -48,9 +48,9 @@
import org.forgerock.opendj.ldap.LDAPClientContext;
import org.forgerock.opendj.ldap.ResultCode;
import org.forgerock.opendj.ldap.ResultHandler;
import org.forgerock.opendj.ldap.SSLContextBuilder;
import org.forgerock.opendj.ldap.SearchResultHandler;
import org.forgerock.opendj.ldap.ServerConnection;
import org.forgerock.opendj.ldap.SSLContextBuilder;
import org.forgerock.opendj.ldap.TrustManagers;
import org.forgerock.opendj.ldap.controls.Control;
import org.forgerock.opendj.ldap.requests.AbandonRequest;
@@ -853,7 +853,7 @@
    }

    @Override
    protected final void handleReadException(FilterChainContext ctx, IOException e) {
    final void handleReadException(FilterChainContext ctx, IOException e) {
        exceptionOccurred(ctx, e);
    }

@@ -869,7 +869,7 @@
     *         new one if no handler have been created yet
     */
    @Override
    protected final LDAPBaseHandler getLDAPHandler(final FilterChainContext ctx) {
    final LDAPBaseHandler getLDAPHandler(final FilterChainContext ctx) {
        Connection<?> connection = ctx.getConnection();
        ServerRequestHandler handler = REQUEST_HANDLER_ATTR.get(connection);
        if (handler == null) {

 opendj-grizzly/src/main/java/org/forgerock/opendj/grizzly/package-info.java

New file
@@ -0,0 +1,48 @@
/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License, Version 1.0 only
 * (the "License").  You may not use this file except in compliance
 * with the License.
 *
 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
 * or http://forgerock.org/license/CDDLv1.0.html.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at legal-notices/CDDLv1_0.txt.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information:
 *      Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 *
 *
 *      Copyright 2013 ForgeRock AS.
 */

/**
 * Provides an implementation of a transport provider using Grizzly as
 * transport. This provider is named "Grizzly".
 * <p>
 * To be used, this implementation must be declared in the
 * provider-configuration file
 * {@code META-INF/services/org.forgerock.opendj.ldap.spi.TransportProvider}
 * with this single line:
 *
 * <pre>
 * com.forgerock.opendj.ldap.GrizzlyTransportProvider
 * </pre>
 *
 * To require that this implementation is used, you must set the transport
 * provider to "Grizzly" using {@code LDAPOptions#setTransportProvider()}
 * method if requesting a {@code LDAPConnectionFactory} or
 * {@code LDAPListenerOptions#setTransportProvider()} method if requesting a
 * {@code LDAPListener}. Otherwise there is no guarantee that this
 * implementation will be used.
 */
package org.forgerock.opendj.grizzly;


 opendj-grizzly/src/test/java/org/forgerock/opendj/grizzly/ASN1BufferReaderTestCase.java

File was renamed from opendj-grizzly/src/test/java/com/forgerock/opendj/grizzly/ASN1BufferReaderTestCase.java
@@ -25,7 +25,7 @@
 *      Portions copyright 2011-2013 ForgeRock AS
 */

package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import java.io.IOException;
import java.nio.ByteBuffer;

 opendj-grizzly/src/test/java/org/forgerock/opendj/grizzly/ASN1BufferWriterTestCase.java

File was renamed from opendj-grizzly/src/test/java/com/forgerock/opendj/grizzly/ASN1BufferWriterTestCase.java
@@ -25,7 +25,7 @@
 *      Portions copyright 2011-2013 ForgeRock AS
 */

package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import java.io.IOException;
import java.nio.ByteBuffer;

 opendj-grizzly/src/test/java/org/forgerock/opendj/grizzly/ConnectionFactoryTestCase.java

File was renamed from opendj-grizzly/src/test/java/com/forgerock/opendj/grizzly/ConnectionFactoryTestCase.java
@@ -25,17 +25,23 @@
 *      Portions copyright 2011-2013 ForgeRock AS
 */

package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import static java.util.Arrays.*;

import static org.fest.assertions.Assertions.*;
import static org.forgerock.opendj.ldap.Connections.*;
import static org.forgerock.opendj.ldap.ErrorResultException.*;
import static org.forgerock.opendj.ldap.TestCaseUtils.*;
import static org.mockito.Matchers.*;
import static org.mockito.Mockito.*;
import static org.testng.Assert.*;
import static java.util.Arrays.asList;
import static org.fest.assertions.Assertions.assertThat;
import static org.forgerock.opendj.ldap.Connections.newFixedConnectionPool;
import static org.forgerock.opendj.ldap.Connections.newHeartBeatConnectionFactory;
import static org.forgerock.opendj.ldap.Connections.newLoadBalancer;
import static org.forgerock.opendj.ldap.ErrorResultException.newErrorResult;
import static org.forgerock.opendj.ldap.TestCaseUtils.findFreeSocketAddress;
import static org.forgerock.opendj.ldap.TestCaseUtils.getServerSocketAddress;
import static org.mockito.Matchers.any;
import static org.mockito.Matchers.anyInt;
import static org.mockito.Mockito.doAnswer;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.when;
import static org.testng.Assert.assertNotNull;
import static org.testng.Assert.assertTrue;

import java.util.Arrays;
import java.util.concurrent.Callable;

 opendj-grizzly/src/test/java/org/forgerock/opendj/grizzly/DefaultTCPNIOTransportTestCase.java

File was renamed from opendj-grizzly/src/test/java/com/forgerock/opendj/grizzly/DefaultTCPNIOTransportTestCase.java
@@ -25,9 +25,9 @@
 *      Portions copyright 2012-2013 ForgeRock AS.
 */

package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import static com.forgerock.opendj.grizzly.DefaultTCPNIOTransport.DEFAULT_TRANSPORT;
import static org.forgerock.opendj.grizzly.DefaultTCPNIOTransport.DEFAULT_TRANSPORT;
import static org.forgerock.opendj.ldap.TestCaseUtils.findFreeSocketAddress;
import static org.testng.Assert.assertTrue;


 opendj-grizzly/src/test/java/org/forgerock/opendj/grizzly/GrizzlyLDAPConnectionFactoryTestCase.java

File was renamed from opendj-grizzly/src/test/java/com/forgerock/opendj/grizzly/GrizzlyLDAPConnectionFactoryTestCase.java
@@ -23,11 +23,11 @@
 *
 *     Copyright 2013 ForgeRock AS.
 */
package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import static org.fest.assertions.Assertions.*;
import static org.forgerock.opendj.ldap.TestCaseUtils.*;
import static org.mockito.Mockito.*;
import static org.fest.assertions.Assertions.assertThat;
import static org.forgerock.opendj.ldap.TestCaseUtils.findFreeSocketAddress;
import static org.mockito.Mockito.mock;

import java.io.IOException;
import java.util.concurrent.Semaphore;

 opendj-grizzly/src/test/java/org/forgerock/opendj/grizzly/GrizzlyLDAPConnectionTestCase.java

File was renamed from opendj-grizzly/src/test/java/com/forgerock/opendj/grizzly/GrizzlyLDAPConnectionTestCase.java
@@ -24,10 +24,12 @@
 *      Copyright 2013 ForgeRock AS.
 */

package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import static org.fest.assertions.Assertions.*;
import static org.mockito.Mockito.*;
import static org.fest.assertions.Assertions.assertThat;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.verifyZeroInteractions;

import java.net.SocketAddress;
import java.util.concurrent.TimeUnit;

 opendj-grizzly/src/test/java/org/forgerock/opendj/grizzly/GrizzlyLDAPListenerTestCase.java

File was renamed from opendj-grizzly/src/test/java/com/forgerock/opendj/grizzly/GrizzlyLDAPListenerTestCase.java
@@ -24,12 +24,12 @@
 *      Copyright 2010 Sun Microsystems, Inc.
 *      Portions copyright 2011-2013 ForgeRock AS.
 */
package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import static org.fest.assertions.Assertions.*;
import static org.fest.assertions.Fail.*;
import static org.forgerock.opendj.ldap.TestCaseUtils.*;
import static org.mockito.Mockito.*;
import static org.fest.assertions.Assertions.assertThat;
import static org.fest.assertions.Fail.fail;
import static org.forgerock.opendj.ldap.TestCaseUtils.findFreeSocketAddress;
import static org.mockito.Mockito.mock;

import java.net.InetSocketAddress;
import java.util.Arrays;

 opendj-grizzly/src/test/java/org/forgerock/opendj/grizzly/GrizzlyLDAPReaderWriterTestCase.java

File was renamed from opendj-grizzly/src/test/java/com/forgerock/opendj/grizzly/GrizzlyLDAPReaderWriterTestCase.java
@@ -23,7 +23,7 @@
 *
 *      Copyright 2013 ForgeRock AS.
 */
package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import org.forgerock.opendj.io.ASN1Reader;
import org.forgerock.opendj.io.ASN1Writer;

 opendj-grizzly/src/test/java/org/forgerock/opendj/grizzly/GrizzlyUtilsTestCase.java

File was renamed from opendj-grizzly/src/test/java/com/forgerock/opendj/grizzly/GrizzlyUtilsTestCase.java
@@ -23,9 +23,9 @@
 *
 *      Copyright 2013 ForgeRock AS.
 */
package com.forgerock.opendj.grizzly;
package org.forgerock.opendj.grizzly;

import static org.fest.assertions.Assertions.*;
import static org.fest.assertions.Assertions.assertThat;

import org.forgerock.opendj.ldap.SdkTestCase;
import org.glassfish.grizzly.StandaloneProcessor;