/*

  * Copyright 2012-2013 smartics, Kronseder & Reiner GmbH

  *

  * Licensed under the Apache License, Version 2.0 (the "License");

  * you may not use this file except in compliance with the License.

  * You may obtain a copy of the License at

  *

  *     http://www.apache.org/licenses/LICENSE-2.0

  *

  * Unless required by applicable law or agreed to in writing, software

  * distributed under the License is distributed on an "AS IS" BASIS,

  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

  * See the License for the specific language governing permissions and

  * limitations under the License.

  */

 package de.smartics.properties.spi.config.definition;

 import java.io.InputStream;

 import de.smartics.properties.api.core.domain.ConfigException;

 import de.smartics.util.lang.classpath.ClassPathContext;

 /**

  * Parses the <code>definition.xml</code> file for properties.

  *

  * @param <T> the type of context the parser creates.

  */

 public interface DefinitionConfigParser<T extends PropertiesDefinitionContext>

 {

   /**

    * Convenience method using a class' class loader to locate the configuration

    * file to parse the configuration file at

    * {@link de.smartics.properties.api.core.domain.PropertiesContext#DEFINITION_FILE}.

    *

    * @param type the type whose class loader to use to locate the configuration

    *          file.

    * @return the read configuration, never <code>null</code>.

    * @throws ConfigException on any problem loading the file.

    */

   T parse(Class<?> type) throws ConfigException;

   /**

    * Parses the configuration file at

    * {@link de.smartics.properties.api.core.domain.PropertiesContext#DEFINITION_FILE}.

    *

    * @param context the class loader with its context to use to locate the

    *          configuration file.

    * @return the read configuration, never <code>null</code>.

    * @throws ConfigException on any problem loading the file.

    */

   T parse(ClassPathContext context)

     throws ConfigException;

   /**

    * Parses the <code>definition.xml</code> from the given stream.

    *

    * @param systemId the identifier of the resource on the stream.

    * @param input the <code>definition.xml</code> on the stream.

    * @return the parsed context.

    * @throws ConfigException on any problem reading from the stream.

    */

   T parse(String systemId, InputStream input)

     throws ConfigException;

 }