001    /*
002     * Copyright 2008-2015 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2008-2015 UnboundID Corp.
007     *
008     * This program is free software; you can redistribute it and/or modify
009     * it under the terms of the GNU General Public License (GPLv2 only)
010     * or the terms of the GNU Lesser General Public License (LGPLv2.1 only)
011     * as published by the Free Software Foundation.
012     *
013     * This program is distributed in the hope that it will be useful,
014     * but WITHOUT ANY WARRANTY; without even the implied warranty of
015     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016     * GNU General Public License for more details.
017     *
018     * You should have received a copy of the GNU General Public License
019     * along with this program; if not, see <http://www.gnu.org/licenses>.
020     */
021    package com.unboundid.ldif;
022    
023    
024    
025    import java.io.Serializable;
026    
027    import com.unboundid.ldap.sdk.DN;
028    import com.unboundid.ldap.sdk.LDAPException;
029    import com.unboundid.util.ByteStringBuffer;
030    
031    
032    
033    /**
034     * This interface defines a common API for LDIF records, which are objects that
035     * can be represented using LDIF.  This includes both
036     * {@code com.unboundid.ldap.sdk.Entry} and {@code LDIFChangeRecord} objects.
037     * It is possible to obtain the DN of an LDIF record, as well as to obtain the
038     * LDIF representation of that object.  They can be read using the
039     * {@code LDIFReader#readLDIFRecord} method and written using the
040     * {@code LDIFWriter#writeLDIFRecord} method.
041     * <BR><BR>
042     * This interface defines a data type that is intended to be implemented only
043     * by classes within the LDAP SDK.  Third-party code may reference objects using
044     * this data type, but external classes should not create additional
045     * implementations of this interface.
046     */
047    public interface LDIFRecord
048           extends Serializable
049    {
050      /**
051       * Retrieves the string representation of the DN for this LDIF record.
052       *
053       * @return  The string representation of the DN for this LDIF record.
054       */
055      String getDN();
056    
057    
058    
059      /**
060       * Retrieves the parsed DN for this LDIF record as a {@code DN} object.
061       *
062       * @return  The parsed DN for this LDIF record as a {@code DN} object.
063       *
064       * @throws  LDAPException  If a problem occurs while trying to parse the DN.
065       */
066      DN getParsedDN()
067         throws LDAPException;
068    
069    
070    
071      /**
072       * Retrieves an LDIF representation of this LDIF record, with each line of
073       * the LDIF representation in a separate element of the returned array.  Long
074       * lines will not be wrapped.
075       *
076       * @return  An LDIF representation of this LDIF record.
077       */
078      String[] toLDIF();
079    
080    
081    
082      /**
083       * Retrieves an LDIF representation of this LDIF record, with each line of
084       * the LDIF representation in a separate element of the returned array.
085       *
086       * @param  wrapColumn  The column at which to wrap long lines.  A value that
087       *                     is less than or equal to two indicates that no
088       *                     wrapping should be performed.
089       *
090       * @return  An LDIF representation of this LDIF record.
091       */
092      String[] toLDIF(final int wrapColumn);
093    
094    
095    
096      /**
097       * Appends an LDIF-formatted string representation of this LDIF record to the
098       * provided buffer.  No wrapping will be performed, and no extra blank lines
099       * will be added.
100       *
101       * @param  buffer  The buffer to which to append the LDIF representation of
102       *                 this LDIF record.
103       */
104      void toLDIF(final ByteStringBuffer buffer);
105    
106    
107    
108      /**
109       * Appends an LDIF-formatted string representation of this LDIF record to the
110       * provided buffer.  No extra blank lines will be added.
111       *
112       * @param  buffer      The buffer to which to append the LDIF representation
113       *                     of this LDIF record.
114       * @param  wrapColumn  The column at which to wrap long lines.  A value that
115       *                     is less than or equal to two indicates that no
116       *                     wrapping should be performed.
117       */
118      void toLDIF(final ByteStringBuffer buffer, final int wrapColumn);
119    
120    
121    
122      /**
123       * Retrieves an LDIF-formatted string representation of this LDIF record.  No
124       * wrapping will be performed, and no extra blank lines will be added.
125       *
126       * @return  An LDIF-formatted string representation of this entry.
127       */
128      String toLDIFString();
129    
130    
131    
132      /**
133       * Retrieves an LDIF-formatted string representation of this LDIF record.  No
134       * extra blank lines will be added.
135       *
136       * @param  wrapColumn  The column at which to wrap long lines.  A value that
137       *                     is less than or equal to two indicates that no
138       *                     wrapping should be performed.
139       *
140       * @return  An LDIF-formatted string representation of this entry.
141       */
142      String toLDIFString(final int wrapColumn);
143    
144    
145    
146      /**
147       * Appends an LDIF-formatted string representation of this LDIF record to the
148       * provided buffer.  No wrapping will be performed, and no extra blank lines
149       * will be added.
150       *
151       * @param  buffer  The buffer to which to append the LDIF representation of
152       *                 this LDIF record.
153       */
154      void toLDIFString(final StringBuilder buffer);
155    
156    
157    
158      /**
159       * Appends an LDIF-formatted string representation of this LDIF record to the
160       * provided buffer.  No extra blank lines will be added.
161       *
162       * @param  buffer      The buffer to which to append the LDIF representation
163       *                     of this LDIF record.
164       * @param  wrapColumn  The column at which to wrap long lines.  A value that
165       *                     is less than or equal to two indicates that no
166       *                     wrapping should be performed.
167       */
168      void toLDIFString(final StringBuilder buffer, final int wrapColumn);
169    
170    
171    
172      /**
173       * Retrieves a string representation of this LDIF record.  Note that it will
174       * be a single-line string representation and will therefore not be an LDIF
175       * representation.
176       *
177       * @return  A string representation of this LDIF record.
178       */
179      @Override()
180      String toString();
181    
182    
183    
184      /**
185       * Appends a string representation of this LDIF record to the provided buffer.
186       * Note that it will be a single-line string representation and will
187       * therefore not be an LDIF representation.
188       *
189       * @param  buffer  The buffer to which the string representation of this LDIF
190       *                 record should be appended.
191       */
192      void toString(final StringBuilder buffer);
193    }