001/*
002 *   Copyright (C) 2005 Christian Schulte <cs@schulte.it>
003 *   All rights reserved.
004 *
005 *   Redistribution and use in source and binary forms, with or without
006 *   modification, are permitted provided that the following conditions
007 *   are met:
008 *
009 *     o Redistributions of source code must retain the above copyright
010 *       notice, this list of conditions and the following disclaimer.
011 *
012 *     o Redistributions in binary form must reproduce the above copyright
013 *       notice, this list of conditions and the following disclaimer in
014 *       the documentation and/or other materials provided with the
015 *       distribution.
016 *
017 *   THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
018 *   INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
019 *   AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
020 *   THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY DIRECT, INDIRECT,
021 *   INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
022 *   NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
023 *   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
024 *   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
025 *   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
026 *   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
027 *
028 *   $JOMC: ModletProvider.java 5101 2016-04-04 18:52:11Z schulte $
029 *
030 */
031package org.jomc.modlet;
032
033/**
034 * {@code Modlet} provider interface.
035 *
036 * @author <a href="mailto:cs@schulte.it">Christian Schulte</a>
037 * @version $JOMC: ModletProvider.java 5101 2016-04-04 18:52:11Z schulte $
038 * @see ModelContext#findModlets(org.jomc.modlet.Modlets)
039 */
040public interface ModletProvider
041{
042
043    /**
044     * Gets the ordinal number of the provider.
045     *
046     * @return The ordinal number of the provider.
047     *
048     * @since 1.6
049     */
050    int getOrdinal();
051
052    /**
053     * Searches a given context for {@code Modlets}.
054     *
055     * @param context The context to search for {@code Modlets}.
056     *
057     * @return The {@code Modlets} found in the context or {@code null}, if no {@code Modlets} are found.
058     *
059     * @throws NullPointerException if {@code context} is {@code null}.
060     * @throws ModelException if searching the context fails.
061     * @deprecated As of JOMC 1.6, replaced by {@link #findModlets(org.jomc.modlet.ModelContext, org.jomc.modlet.Modlets)}.
062     * This method will be removed in JOMC 2.0.
063     */
064    @Deprecated
065    Modlets findModlets( ModelContext context ) throws NullPointerException, ModelException;
066
067    /**
068     * Searches a given context for {@code Modlets}.
069     *
070     * @param context The context to search for {@code Modlets}.
071     * @param modlets The {@code Modlets} currently being searched.
072     *
073     * @return The {@code Modlets} found in the context or {@code null}, if no {@code Modlets} are found.
074     *
075     * @throws NullPointerException if {@code context} or {@code modlets} is {@code null}.
076     * @throws ModelException if searching the context fails.
077     * @since 1.6
078     */
079    Modlets findModlets( ModelContext context, Modlets modlets ) throws NullPointerException, ModelException;
080
081}