org.metawidget.config.iface.ConfigReader Maven / Gradle / Ivy
// Metawidget
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of the GNU Lesser General Public
// License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
//
// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
// Lesser General Public License for more details.
//
// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
package org.metawidget.config.iface;
import java.io.InputStream;
import org.metawidget.iface.Immutable;
/**
* Reads metadata.xml files and configures Metawidgets.
*
* In spirit, metadata.xml is a general-purpose mechanism for configuring JavaBeans
* based on XML files. In practice, there are some Metawidget-specific features such as:
*
*
* - support for reusing immutable objects (as defined by
isImmutable)
* - caching XML input based on resource name (uses
XmlUtils.CachingContextHandler)
* - resolving resources from specialized locations, such as under
WEB-INF using
* ServletContext.getResource (ConfigReader implements
* ResourceResolver)
*
*
* This mechanism is not just static methods, because ConfigReaders need to be able to be subclassed
* (eg. ServletConfigReader)
*
Important
*
* ConfigReader's support for reusing immutable objects (eg. JpaInspector)
* that use config objects (eg. JpaInspectorConfig) is dependant on the config object
* overriding equals and hashCode. Failure to override these
* methods may result in your object not being reused, or being reused inappropriately.
*
* @author Richard Kennard
*/
public interface ConfigReader
extends Immutable {
//
// Methods
//
/**
* Read configuration from an application resource.
*
* This version of configure uses openResource to open the specified
* resource. It assumes the resource name is a unique key, so subsequent calls do not need to
* re-open the resource, or re-parse it, making this version of configure much
* faster than configure( InputStream, Object ).
*
* This version further caches any immutable objects, in the same way as
* configure( InputStream, Object ) (see the JavaDoc for that method).
*
* @param resource
* resource name that will be looked up using openResource
* @param toConfigure
* object to configure. Can be a subclass of the one actually in the resource
* @param names
* path to a property within the object. If specified, siblings to this path will be
* ignored. This allows ConfigReader to be used to initialise only a specific part of
* an object
*/
Object configure( String resource, Object toConfigure, String... names );
/**
* Read configuration from an input stream.
*
* This version of configure caches any immutable objects (as determined by
* isImmutable) and reuses them for subsequent calls. This helps ensure there is
* only ever one instance of a, say, Inspector or WidgetBuilder.
*
* If the Object to configure is a Class, this method will create and return an
* instance of that class based on the configuration file. For example, if the configuration
* file is...
*
*
* <metawidget>
* <myInspector config="myConfig">
* <someConfigParameter/>
* </myInspector>
* </metawidget>
*
*
* ...then the code...
*
*
* Inspector myInspector = myConfigReader.configure( stream, Inspector.class );
*
*
* ...will create a MyInspector configured with someConfigParameter.
*
* Conversely, if the Object to configure is already an instance, this method will configure the
* instance. For example if the configuration file is...
*
*
* <metawidget>
* <swingMetawidget>
* <opaque><boolean>true</boolean></opaque>
* </swingMetawidget>
* </metawidget>
*
*
* ...then the code...
*
*
* JPanel panel = new JPanel();
* myConfigReader.configure( stream, panel );
*
*
* ...will call setOpaque on the given JPanel.
*
* @param stream
* XML input as a stream
* @param toConfigure
* object to configure. Can be a subclass of the one actually in the resource
* @param names
* path to a property within the object. If specified, siblings to this path will be
* ignored. This allows ConfigReader to be used to initialise only a specific part of
* an object
*/
Object configure( InputStream stream, Object toConfigure, String... names );
}