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 }