001    /*
002     * Copyright 2008-2016 UnboundID Corp.
003     * All Rights Reserved.
004     */
005    /*
006     * Copyright (C) 2008-2016 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    import com.unboundid.util.NotExtensible;
031    import com.unboundid.util.ThreadSafety;
032    import com.unboundid.util.ThreadSafetyLevel;
033    
034    
035    
036    /**
037     * This interface defines a common API for LDIF records, which are objects that
038     * can be represented using LDIF.  This includes both
039     * {@link com.unboundid.ldap.sdk.Entry} and {@link LDIFChangeRecord} objects.
040     * It is possible to obtain the DN of an LDIF record, as well as to obtain the
041     * LDIF representation of that object.  They can be read using the
042     * {@link LDIFReader#readLDIFRecord} method and written using the
043     * {@link LDIFWriter#writeLDIFRecord} method.
044     * <BR><BR>
045     * This interface defines a data type that is intended to be implemented only
046     * by classes within the LDAP SDK.  Third-party code may reference objects using
047     * this data type, but external classes should not create additional
048     * implementations of this interface.
049     */
050    @NotExtensible()
051    @ThreadSafety(level=ThreadSafetyLevel.INTERFACE_THREADSAFE)
052    public interface LDIFRecord
053           extends Serializable
054    {
055      /**
056       * Retrieves the string representation of the DN for this LDIF record.
057       *
058       * @return  The string representation of the DN for this LDIF record.
059       */
060      String getDN();
061    
062    
063    
064      /**
065       * Retrieves the parsed DN for this LDIF record as a {@link DN} object.
066       *
067       * @return  The parsed DN for this LDIF record as a {@link DN} object.
068       *
069       * @throws  LDAPException  If a problem occurs while trying to parse the DN.
070       */
071      DN getParsedDN()
072         throws LDAPException;
073    
074    
075    
076      /**
077       * Retrieves an LDIF representation of this LDIF record, with each line of
078       * the LDIF representation in a separate element of the returned array.  Long
079       * lines will not be wrapped.
080       *
081       * @return  An LDIF representation of this LDIF record.
082       */
083      String[] toLDIF();
084    
085    
086    
087      /**
088       * Retrieves an LDIF representation of this LDIF record, with each line of
089       * the LDIF representation in a separate element of the returned array.
090       *
091       * @param  wrapColumn  The column at which to wrap long lines.  A value that
092       *                     is less than or equal to two indicates that no
093       *                     wrapping should be performed.
094       *
095       * @return  An LDIF representation of this LDIF record.
096       */
097      String[] toLDIF(final int wrapColumn);
098    
099    
100    
101      /**
102       * Appends an LDIF-formatted string representation of this LDIF record to the
103       * provided buffer.  No wrapping will be performed, and no extra blank lines
104       * will be added.
105       *
106       * @param  buffer  The buffer to which to append the LDIF representation of
107       *                 this LDIF record.
108       */
109      void toLDIF(final ByteStringBuffer buffer);
110    
111    
112    
113      /**
114       * Appends an LDIF-formatted string representation of this LDIF record to the
115       * provided buffer.  No extra blank lines will be added.
116       *
117       * @param  buffer      The buffer to which to append the LDIF representation
118       *                     of this LDIF record.
119       * @param  wrapColumn  The column at which to wrap long lines.  A value that
120       *                     is less than or equal to two indicates that no
121       *                     wrapping should be performed.
122       */
123      void toLDIF(final ByteStringBuffer buffer, final int wrapColumn);
124    
125    
126    
127      /**
128       * Retrieves an LDIF-formatted string representation of this LDIF record.  No
129       * wrapping will be performed, and no extra blank lines will be added.
130       *
131       * @return  An LDIF-formatted string representation of this entry.
132       */
133      String toLDIFString();
134    
135    
136    
137      /**
138       * Retrieves an LDIF-formatted string representation of this LDIF record.  No
139       * extra blank lines will be added.
140       *
141       * @param  wrapColumn  The column at which to wrap long lines.  A value that
142       *                     is less than or equal to two indicates that no
143       *                     wrapping should be performed.
144       *
145       * @return  An LDIF-formatted string representation of this entry.
146       */
147      String toLDIFString(final int wrapColumn);
148    
149    
150    
151      /**
152       * Appends an LDIF-formatted string representation of this LDIF record to the
153       * provided buffer.  No wrapping will be performed, and no extra blank lines
154       * will be added.
155       *
156       * @param  buffer  The buffer to which to append the LDIF representation of
157       *                 this LDIF record.
158       */
159      void toLDIFString(final StringBuilder buffer);
160    
161    
162    
163      /**
164       * Appends an LDIF-formatted string representation of this LDIF record to the
165       * provided buffer.  No extra blank lines will be added.
166       *
167       * @param  buffer      The buffer to which to append the LDIF representation
168       *                     of this LDIF record.
169       * @param  wrapColumn  The column at which to wrap long lines.  A value that
170       *                     is less than or equal to two indicates that no
171       *                     wrapping should be performed.
172       */
173      void toLDIFString(final StringBuilder buffer, final int wrapColumn);
174    
175    
176    
177      /**
178       * Retrieves a string representation of this LDIF record.  Note that it will
179       * be a single-line string representation and will therefore not be an LDIF
180       * representation.
181       *
182       * @return  A string representation of this LDIF record.
183       */
184      @Override()
185      String toString();
186    
187    
188    
189      /**
190       * Appends a string representation of this LDIF record to the provided buffer.
191       * Note that it will be a single-line string representation and will
192       * therefore not be an LDIF representation.
193       *
194       * @param  buffer  The buffer to which the string representation of this LDIF
195       *                 record should be appended.
196       */
197      void toString(final StringBuilder buffer);
198    }