001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2009 Sun Microsystems, Inc.
015 * Portions Copyright 2012-2016 ForgeRock AS.
016 */
017
018package org.forgerock.opendj.ldif;
019
020import org.forgerock.opendj.ldap.Connection;
021import org.forgerock.opendj.ldap.Entry;
022import org.forgerock.opendj.ldap.LdapException;
023
024import org.forgerock.util.Reject;
025
026/**
027 * A {@code ConnectionEntryWriter} is a bridge from {@code Connection}s to
028 * {@code EntryWriter}s. A connection entry writer writes entries by sending Add
029 * requests to an underlying connection.
030 * <p>
031 * All Add requests are performed synchronously, blocking until an Add result is
032 * received. If an Add result indicates that an Add request has failed for some
033 * reason then the error result is propagated to the caller using an
034 * {@code LdapException}.
035 * <p>
036 * <b>Note:</b> comments are not supported by connection change record writers.
037 * Attempts to write comments will be ignored.
038 */
039public final class ConnectionEntryWriter implements EntryWriter {
040    private final Connection connection;
041
042    /**
043     * Creates a new connection entry writer whose destination is the provided
044     * connection.
045     *
046     * @param connection
047     *            The connection to use.
048     * @throws NullPointerException
049     *             If {@code connection} was {@code null}.
050     */
051    public ConnectionEntryWriter(final Connection connection) {
052        Reject.ifNull(connection);
053        this.connection = connection;
054    }
055
056    /**
057     * Closes this connection entry writer, including the underlying connection.
058     * Closing a previously closed entry writer has no effect.
059     */
060    @Override
061    public void close() {
062        connection.close();
063    }
064
065    /**
066     * Connection entry writers do not require flushing, so this method has no
067     * effect.
068     */
069    @Override
070    public void flush() {
071        // Do nothing.
072    }
073
074    /**
075     * Connection entry writers do not support comments, so the provided comment
076     * will be ignored.
077     *
078     * @param comment
079     *            The {@code CharSequence} to be written as a comment.
080     * @return A reference to this connection entry writer.
081     * @throws NullPointerException
082     *             If {@code comment} was {@code null}.
083     */
084    @Override
085    public ConnectionEntryWriter writeComment(final CharSequence comment) {
086        Reject.ifNull(comment);
087
088        // Do nothing.
089        return this;
090    }
091
092    /**
093     * Writes an entry to the underlying connection using an Add request,
094     * blocking until the request completes.
095     *
096     * @param entry
097     *            The {@code Entry} to be written.
098     * @return A reference to this connection entry writer.
099     * @throws LdapException
100     *             If the result code indicates that the request failed for some
101     *             reason.
102     * @throws NullPointerException
103     *             If {@code entry} was {@code null}.
104     */
105    @Override
106    public ConnectionEntryWriter writeEntry(final Entry entry) throws LdapException {
107        Reject.ifNull(entry);
108        connection.add(entry);
109        return this;
110    }
111
112}