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