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 java.io.Closeable;
021import java.io.Flushable;
022import java.io.IOException;
023
024import org.forgerock.opendj.ldap.Entry;
025
026/**
027 * An interface for writing entries to a data source, typically an LDIF file.
028 */
029public interface EntryWriter extends Closeable, Flushable {
030    /**
031     * Closes this entry writer, flushing it first. Closing a previously closed
032     * entry writer has no effect.
033     *
034     * @throws IOException
035     *             If an unexpected IO error occurred while closing.
036     */
037    @Override
038    void close() throws IOException;
039
040    /**
041     * Flushes this entry writer so that any buffered data is written
042     * immediately to underlying stream, flushing the stream if it is also
043     * {@code Flushable}.
044     * <p>
045     * If the intended destination of this stream is an abstraction provided by
046     * the underlying operating system, for example a file, then flushing the
047     * stream guarantees only that bytes previously written to the stream are
048     * passed to the operating system for writing; it does not guarantee that
049     * they are actually written to a physical device such as a disk drive.
050     *
051     * @throws IOException
052     *             If an unexpected IO error occurred while flushing.
053     */
054    @Override
055    void flush() throws IOException;
056
057    /**
058     * Writes a comment.
059     *
060     * @param comment
061     *            The {@code CharSequence} to be written as a comment.
062     * @return A reference to this entry writer.
063     * @throws IOException
064     *             If an unexpected IO error occurred while writing the comment.
065     * @throws NullPointerException
066     *             If {@code comment} was {@code null}.
067     */
068    EntryWriter writeComment(CharSequence comment) throws IOException;
069
070    /**
071     * Writes an entry.
072     *
073     * @param entry
074     *            The {@code Entry} to be written.
075     * @return A reference to this entry writer.
076     * @throws IOException
077     *             If an unexpected IO error occurred while writing the entry.
078     * @throws NullPointerException
079     *             If {@code entry} was {@code null}.
080     */
081    EntryWriter writeEntry(Entry entry) throws IOException;
082
083}