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