001/*
002 * CDDL HEADER START
003 *
004 * The contents of this file are subject to the terms of the
005 * Common Development and Distribution License, Version 1.0 only
006 * (the "License").  You may not use this file except in compliance
007 * with the License.
008 *
009 * You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
010 * or http://forgerock.org/license/CDDLv1.0.html.
011 * See the License for the specific language governing permissions
012 * and limitations under the License.
013 *
014 * When distributing Covered Code, include this CDDL HEADER in each
015 * file and include the License file at legal-notices/CDDLv1_0.txt.
016 * If applicable, add the following below this CDDL HEADER, with the
017 * fields enclosed by brackets "[]" replaced with your own identifying
018 * information:
019 *      Portions Copyright [yyyy] [name of copyright owner]
020 *
021 * CDDL HEADER END
022 *
023 *      Copyright 2011 ForgeRock AS
024 */
025
026package org.forgerock.opendj.ldif;
027
028import java.util.List;
029
030import org.forgerock.i18n.LocalizableMessage;
031import org.forgerock.opendj.ldap.DecodeException;
032
033/**
034 * A listener interface which is notified whenever LDIF records are skipped,
035 * malformed, or fail schema validation.
036 * <p>
037 * By default the {@link #FAIL_FAST} listener is used.
038 */
039public interface RejectedLDIFListener {
040    /**
041     * The default handler which ignores skipped records but which terminates
042     * processing by throwing a {@code DecodeException} as soon as a record is
043     * found to be malformed or rejected due to a schema validation failure.
044     */
045    RejectedLDIFListener FAIL_FAST = new RejectedLDIFListener() {
046
047        @Override
048        public void handleMalformedRecord(final long lineNumber, final List<String> lines,
049                final LocalizableMessage reason) throws DecodeException {
050            // Fail fast.
051            throw DecodeException.error(reason);
052        }
053
054        @Override
055        public void handleSchemaValidationFailure(final long lineNumber, final List<String> lines,
056                final List<LocalizableMessage> reasons) throws DecodeException {
057            // Fail fast - just use first message.
058            throw DecodeException.error(reasons.get(0));
059        }
060
061        @Override
062        public void handleSchemaValidationWarning(final long lineNumber, final List<String> lines,
063                final List<LocalizableMessage> reasons) throws DecodeException {
064            // Ignore schema validation warnings.
065        }
066
067        @Override
068        public void handleSkippedRecord(final long lineNumber, final List<String> lines,
069                final LocalizableMessage reason) throws DecodeException {
070            // Ignore skipped records.
071        }
072    };
073
074    /**
075     * A handler which ignores all rejected record notifications.
076     */
077    RejectedLDIFListener IGNORE_ALL = new RejectedLDIFListener() {
078
079        @Override
080        public void handleMalformedRecord(final long lineNumber, final List<String> lines,
081                final LocalizableMessage reason) throws DecodeException {
082            // Ignore malformed records.
083        }
084
085        @Override
086        public void handleSchemaValidationFailure(final long lineNumber, final List<String> lines,
087                final List<LocalizableMessage> reasons) throws DecodeException {
088            // Ignore schema validation failures.
089        }
090
091        @Override
092        public void handleSchemaValidationWarning(final long lineNumber, final List<String> lines,
093                final List<LocalizableMessage> reasons) throws DecodeException {
094            // Ignore schema validation warnings.
095        }
096
097        @Override
098        public void handleSkippedRecord(final long lineNumber, final List<String> lines,
099                final LocalizableMessage reason) throws DecodeException {
100            // Ignore skipped records.
101        }
102    };
103
104    /**
105     * Invoked when a record was rejected because it was malformed in some way
106     * and could not be decoded.
107     *
108     * @param lineNumber
109     *            The line number within the source location in which the
110     *            malformed record is located, if known, otherwise {@code -1}.
111     * @param lines
112     *            The content of the malformed record.
113     * @param reason
114     *            The reason why the record is malformed.
115     * @throws DecodeException
116     *             If processing should terminate.
117     */
118    void handleMalformedRecord(long lineNumber, List<String> lines, LocalizableMessage reason)
119            throws DecodeException;
120
121    /**
122     * Invoked when a record was rejected because it does not conform to the
123     * schema and schema validation is enabled.
124     *
125     * @param lineNumber
126     *            The line number within the source location in which the
127     *            rejected record is located, if known, otherwise {@code -1}.
128     * @param lines
129     *            The content of the record which failed schema validation.
130     * @param reasons
131     *            The reasons why the record failed schema validation.
132     * @throws DecodeException
133     *             If processing should terminate.
134     */
135    void handleSchemaValidationFailure(long lineNumber, List<String> lines,
136            List<LocalizableMessage> reasons) throws DecodeException;
137
138    /**
139     * Invoked when a record was not rejected but contained one or more schema
140     * validation warnings.
141     *
142     * @param lineNumber
143     *            The line number within the source location in which the record
144     *            is located, if known, otherwise {@code -1}.
145     * @param lines
146     *            The content of the record which contained schema validation
147     *            warnings.
148     * @param reasons
149     *            The schema validation warnings.
150     * @throws DecodeException
151     *             If processing should terminate.
152     */
153    void handleSchemaValidationWarning(long lineNumber, List<String> lines,
154            List<LocalizableMessage> reasons) throws DecodeException;
155
156    /**
157     * Invoked when a record was skipped because it did not match filter
158     * criteria defined by the reader.
159     *
160     * @param lineNumber
161     *            The line number within the source location in which the
162     *            skipped record is located, if known, otherwise {@code -1}.
163     * @param lines
164     *            The content of the record which was skipped.
165     * @param reason
166     *            The reason why the record was skipped.
167     * @throws DecodeException
168     *             If processing should terminate.
169     */
170    void handleSkippedRecord(long lineNumber, List<String> lines, LocalizableMessage reason)
171            throws DecodeException;
172
173}