001 /*
002 * Copyright 2008-2014 UnboundID Corp.
003 * All Rights Reserved.
004 */
005 /*
006 * Copyright (C) 2008-2014 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 }