001package org.apache.maven.configuration;
002
003/*
004 * Licensed to the Apache Software Foundation (ASF) under one
005 * or more contributor license agreements.  See the NOTICE file
006 * distributed with this work for additional information
007 * regarding copyright ownership.  The ASF licenses this file
008 * to you under the Apache License, Version 2.0 (the
009 * "License"); you may not use this file except in compliance
010 * with the License.  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,
015 * software distributed under the License is distributed on an
016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017 * KIND, either express or implied.  See the License for the
018 * specific language governing permissions and limitations
019 * under the License.
020 */
021
022/**
023 * A request to configure a bean from some configuration in the POM or similar.
024 * 
025 * @author Benjamin Bentmann
026 */
027public interface BeanConfigurationRequest
028{
029
030    /**
031     * Gets the bean to configure. Eventually, a valid request must have a bean set.
032     * 
033     * @return The bean to configure, or {@code null} if none.
034     */
035    Object getBean();
036
037    /**
038     * Sets the bean to configure. Eventually, a valid request must have a bean set.
039     * 
040     * @param bean The bean to configure, may be {@code null}.
041     * @return This request for chaining, never {@code null}.
042     */
043    BeanConfigurationRequest setBean( Object bean );
044
045    /**
046     * Gets the configuration to unmarshal into the bean.
047     * 
048     * @return The configuration to unmarshal into the bean or {@code null} if none.
049     */
050    Object getConfiguration();
051
052    /**
053     * Sets the configuration to unmarshal into the bean. The configuration should be taken from
054     * {@link org.apache.maven.model.ConfigurationContainer#getConfiguration()} or a similar source.
055     * Fully equivalent to {@code setConfiguration(configuration, null)}.
056     * 
057     * @param configuration The configuration to unmarshal, may be {@code null}.
058     * @return This request for chaining, never {@code null}.
059     */
060    BeanConfigurationRequest setConfiguration( Object configuration );
061
062    /**
063     * Sets the configuration to unmarshal into the bean. The configuration should be taken from
064     * {@link org.apache.maven.model.ConfigurationContainer#getConfiguration()} or a similar source.
065     * If {@code element} is not {@code null}, child configuration element with the specified name will 
066     * be unmarshaled.
067     * 
068     * @param configuration The configuration to unmarshal, may be {@code null}.
069     * @param element Configuration element name to unmarshal or {@code null} to unmarshal entire configuration.
070     * @return This request for chaining, never {@code null}.
071     */
072    BeanConfigurationRequest setConfiguration( Object configuration, String element );
073
074    /**
075     * Returns configuration element name or {@code null}. 
076     * 
077     * @see #setConfiguration(Object, String)
078     * 
079     * @return Configuration element name or {@code null}
080     */
081    String getConfigurationElement();
082
083    /**
084     * Gets the class loader from which to load any types referenced by the configuration. If unset, the class loader of
085     * the bean class will be used.
086     * 
087     * @return The class loader to load referenced types from or {@code null} if unset.
088     */
089    ClassLoader getClassLoader();
090
091    /**
092     * Sets the class loader from which to load any types referenced by the configuration. If unset, the class loader of
093     * the bean class will be used.
094     * 
095     * @param classLoader The class loader to load referenced types from, may be {@code null}.
096     * @return This request for chaining, never {@code null}.
097     */
098    BeanConfigurationRequest setClassLoader( ClassLoader classLoader );
099
100    /**
101     * Gets the optional preprocessor for configuration values.
102     * 
103     * @return The preprocessor for configuration values or {@code null} if none.
104     */
105    BeanConfigurationValuePreprocessor getValuePreprocessor();
106
107    /**
108     * Sets the optional preprocessor for configuration values.
109     * 
110     * @param valuePreprocessor The preprocessor for configuration values, may be {@code null} if unneeded.
111     * @return This request for chaining, never {@code null}.
112     */
113    BeanConfigurationRequest setValuePreprocessor( BeanConfigurationValuePreprocessor valuePreprocessor );
114
115    /**
116     * Gets the optional path translator for configuration values unmarshalled to files.
117     * 
118     * @return The path translator for files or {@code null} if none.
119     */
120    BeanConfigurationPathTranslator getPathTranslator();
121
122    /**
123     * Sets the optional path translator for configuration values unmarshalled to files.
124     * 
125     * @param pathTranslator The path translator for files, may be {@code null} if unneeded.
126     * @return This request for chaining, never {@code null}.
127     */
128    BeanConfigurationRequest setPathTranslator( BeanConfigurationPathTranslator pathTranslator );
129
130}