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.requests.AddRequest;
025import org.forgerock.opendj.ldap.requests.DeleteRequest;
026import org.forgerock.opendj.ldap.requests.ModifyDNRequest;
027import org.forgerock.opendj.ldap.requests.ModifyRequest;
028
029/**
030 * An interface for writing change records to a data source, typically an LDIF
031 * file.
032 */
033public interface ChangeRecordWriter extends Closeable, Flushable {
034    /**
035     * Closes this change record writer, flushing it first. Closing a previously
036     * closed change record writer has no effect.
037     *
038     * @throws IOException
039     *             If an unexpected IO error occurred while closing.
040     */
041    @Override
042    void close() throws IOException;
043
044    /**
045     * Flushes this change record writer so that any buffered data is written
046     * immediately to underlying stream, flushing the stream if it is also
047     * {@code Flushable}.
048     * <p>
049     * If the intended destination of this stream is an abstraction provided by
050     * the underlying operating system, for example a file, then flushing the
051     * stream guarantees only that bytes previously written to the stream are
052     * passed to the operating system for writing; it does not guarantee that
053     * they are actually written to a physical device such as a disk drive.
054     *
055     * @throws IOException
056     *             If an unexpected IO error occurred while flushing.
057     */
058    @Override
059    void flush() throws IOException;
060
061    /**
062     * Writes an {@code Add} change record.
063     *
064     * @param change
065     *            The {@code AddRequest} to be written as an {@code Add} change
066     *            record.
067     * @return A reference to this change record writer.
068     * @throws IOException
069     *             If an unexpected IO error occurred while writing the change
070     *             record.
071     * @throws NullPointerException
072     *             If {@code change} was {@code null}.
073     */
074    ChangeRecordWriter writeChangeRecord(AddRequest change) throws IOException;
075
076    /**
077     * Writes a change record.
078     *
079     * @param change
080     *            The {@code ChangeRecord} to be written.
081     * @return A reference to this change record writer.
082     * @throws IOException
083     *             If an unexpected IO error occurred while writing the change
084     *             record.
085     * @throws NullPointerException
086     *             If {@code change} was {@code null}.
087     */
088    ChangeRecordWriter writeChangeRecord(ChangeRecord change) throws IOException;
089
090    /**
091     * Writes a {@code Delete} change record.
092     *
093     * @param change
094     *            The {@code DeleteRequest} to be written as an {@code Delete}
095     *            change record.
096     * @return A reference to this change record writer.
097     * @throws IOException
098     *             If an unexpected IO error occurred while writing the change
099     *             record.
100     * @throws NullPointerException
101     *             If {@code change} was {@code null}.
102     */
103    ChangeRecordWriter writeChangeRecord(DeleteRequest change) throws IOException;
104
105    /**
106     * Writes a {@code ModifyDN} change record.
107     *
108     * @param change
109     *            The {@code ModifyDNRequest} to be written as an
110     *            {@code ModifyDN} change record.
111     * @return A reference to this change record writer.
112     * @throws IOException
113     *             If an unexpected IO error occurred while writing the change
114     *             record.
115     * @throws NullPointerException
116     *             If {@code change} was {@code null}.
117     */
118    ChangeRecordWriter writeChangeRecord(ModifyDNRequest change) throws IOException;
119
120    /**
121     * Writes a {@code Modify} change record.
122     *
123     * @param change
124     *            The {@code ModifyRequest} to be written as an {@code Modify}
125     *            change record.
126     * @return A reference to this change record writer.
127     * @throws IOException
128     *             If an unexpected IO error occurred while writing the change
129     *             record.
130     * @throws NullPointerException
131     *             If {@code change} was {@code null}.
132     */
133    ChangeRecordWriter writeChangeRecord(ModifyRequest change) throws IOException;
134
135    /**
136     * Writes a comment.
137     *
138     * @param comment
139     *            The {@code CharSequence} to be written as a comment.
140     * @return A reference to this change record writer.
141     * @throws IOException
142     *             If an unexpected IO error occurred while writing the comment.
143     * @throws NullPointerException
144     *             If {@code comment} was {@code null}.
145     */
146    ChangeRecordWriter writeComment(CharSequence comment) throws IOException;
147
148}