001/*
002 * Copyright 2008-2017 UnboundID Corp.
003 * All Rights Reserved.
004 */
005/*
006 * Copyright (C) 2008-2017 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 */
021package com.unboundid.ldif;
022
023
024
025import java.io.Serializable;
026
027import com.unboundid.ldap.sdk.DN;
028import com.unboundid.ldap.sdk.LDAPException;
029import com.unboundid.util.ByteStringBuffer;
030import com.unboundid.util.NotExtensible;
031import com.unboundid.util.ThreadSafety;
032import 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)
052public 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}