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