Package eu.woolplatform.utils

Class AppComponents

java.lang.Object

eu.woolplatform.utils.AppComponents

public class AppComponents
extends Object

This class defines a set of application-wide components. They can be built and configured from an XML file, similar to Java Beans. This class can also create default instances on request.

Components can be specified in an XML element "component". It should have an attribute "class" with the qualified class name of the component. This class will attempt to build the component with the default constructor of that class. If there is no (accessible) default constructor, it will try the static method getInstance().

The XML element "component" can have zero or more child elements "attribute". The element should have two attributes: "name" and "value". If the name is "myAttr", it will try to write the specified value to member variable "myAttr". If the class does not have an accessible member variable "myAttr", it will try the method setMyAttr().

The specified attribute value should be a string representation for the type of attribute. This can be a primitive type, a date/time type (described next) or a class that has a constructor that takes one string. You may register additional types. This is described further below.

Date/time attributes can have one of the following types:

• long/Long (UNIX timestamp in milliseconds)
• Date
• Instant
• Calendar
• DateTime
• LocalDate
• LocalTime
• LocalDateTime

They are parsed using parseDateTime()

Components are built with one of the methods buildComponents(), which take either an entire XML document (as a file, URL, input stream or parsed document) or one XML element. If you pass an entire document, it will search for "component" elements as direct children of the document's root element. If you pass an XML element, it will search the direct children of that element.

The method getComponent() returns components. If a component is requested that has not been built in buildComponents(), it will try to create a default instance. It will try the default constructor or static method getInstance(), without setting any attributes.

Register custom attribute types

In addition to the default set of supported attribute types (primitive, date/time, string constructor), you can register additional types. They have higher priority than the default types, so you may even override those types. To register a custom type, call addAttributeMapping() before buildComponents(). If a field has a matching class, the attribute mapping will be used to parse the string value of the attribute from the XML element of the component.

Method Summary

Modifier and Type	Method	Description
<T> void	addAttributeMapping(AppComponentAttributeMapping<T> mapping)	Adds an attribute mapping.
void	addComponent(Object component)	Adds the specified component.
void	buildComponents(File config)	Builds components from the specified XML configuration file.
void	buildComponents(InputStream config)	Builds components from the specified XML configuration file.
void	buildComponents(URL config)	Builds components from the specified XML configuration file.
void	buildComponents(Document doc)	Builds components from the specified XML configuration document.
void	buildComponents(Element elem)	Builds components from the specified XML element.
<T> T	findComponent(Class<T> clazz)	Tries to find a component of the specified class or a subclass.
static <T> T	get(Class<T> clazz)	This is a shortcut method for getInstance().getComponent().
<T> T	getComponent(Class<T> clazz)	Tries to find a component of the specified class or a subclass.
<T> T	getComponent(Class<T> clazz, T defaultVal)	Tries to find a component of the specified class or a subclass.
static AppComponents	getInstance()	Returns the singleton instance of this class.
static org.slf4j.Logger	getLogger(String name)	This is a shortcut method to get a logger.
boolean	hasComponent(Class<?> clazz)	Returns whether there is a component of the specified class or a subclass.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static AppComponents getInstance()

Returns the singleton instance of this class.

Returns:

the singleton instance of this class

getLogger

public static org.slf4j.Logger getLogger(String name)

This is a shortcut method to get a logger. It will try to get an app component of class ILoggerFactory from SLF4J. If it doesn't exist, it will get the default SLF4J factory (which is then added as an app component). Then it gets the logger with the specified name from that factory.

Parameters:

name - the logger name

Returns:

the logger

get

public static <T> T get(Class<T> clazz)
                 throws RuntimeException

This is a shortcut method for getInstance().getComponent(). It tries to find a component of the specified class or a subclass. If no such component is found, it will try to create a default instance of the specified class. The new component will then be added to the collection so the same instance can be retrieved later.

Type Parameters:

T - the type of component

Parameters:

clazz - the component class

Returns:

the component

Throws:

RuntimeException - if a default instance cannot be created

addAttributeMapping

public <T> void addAttributeMapping(AppComponentAttributeMapping<T> mapping)

Adds an attribute mapping. This registers a custom attribute type that can be used when the components are built from XML. If an attribute has a matching class, the mapping will be used to parse the string value from the XML element of a component.

Type Parameters:

T - the attribute class

Parameters:

mapping - the attribute mapping

buildComponents

public void buildComponents(File config)
                     throws IOException,
                            ParseException,
                            BuildException

Builds components from the specified XML configuration file. It searches for XML elements "component" as direct children of the root element in the XML document.

Parameters:

config - the XML configuration file

Throws:

IOException - if an error occurs while reading the file

ParseException - if the XML content is invalid

BuildException - if an error occurs while building a component

buildComponents

public void buildComponents(URL config)
                     throws IOException,
                            ParseException,
                            BuildException

Builds components from the specified XML configuration file. It searches for XML elements "component" as direct children of the root element in the XML document.

Parameters:

config - the URL of the XML configuration file

Throws:

IOException - if an error occurs while reading the file

ParseException - if the XML content is invalid

BuildException - if an error occurs while building a component

buildComponents

public void buildComponents(InputStream config)
                     throws IOException,
                            ParseException,
                            BuildException

Builds components from the specified XML configuration file. It searches for XML elements "component" as direct children of the root element in the XML document.

Parameters:

config - the XML configuration file as an input stream

Throws:

IOException - if an error occurs while reading the file

ParseException - if the XML content is invalid

BuildException - if an error occurs while building a component

buildComponents

public void buildComponents(Document doc)
                     throws ParseException,
                            BuildException

Builds components from the specified XML configuration document. It searches for XML elements "component" as direct children of the root element in the document.

Parameters:

doc - the XML configuration document

Throws:

ParseException - if the XML content is invalid

BuildException - if an error occurs while building a component

buildComponents

public void buildComponents(Element elem)
                     throws ParseException,
                            BuildException

Builds components from the specified XML element. It searches for XML elements "component" as direct children of the specified element.

Parameters:

elem - the XML element

Throws:

ParseException - if the XML content is invalid

BuildException - if an error occurs while building a component

addComponent

public void addComponent(Object component)

Adds the specified component.

Parameters:

component - the component

hasComponent

public boolean hasComponent(Class<?> clazz)

Returns whether there is a component of the specified class or a subclass.

Parameters:

clazz - the component class

Returns:

true if there is a component, false otherwise

findComponent

public <T> T findComponent(Class<T> clazz)

Tries to find a component of the specified class or a subclass. If no such component is found, this method returns null.

Type Parameters:

T - the type of component

Parameters:

clazz - the component class

Returns:

the component or null

getComponent

public <T> T getComponent(Class<T> clazz)
                   throws RuntimeException

Tries to find a component of the specified class or a subclass. If no such component is found, it will try to create a default instance of the specified class. The new component will then be added to the collection so the same instance can be retrieved later.

Type Parameters:

T - the type of component

Parameters:

clazz - the component class

Returns:

the component

Throws:

RuntimeException - if a default instance cannot be created

getComponent

public <T> T getComponent(Class<T> clazz,
                          T defaultVal)

Tries to find a component of the specified class or a subclass. If no such component is found, it will try to create a default instance of the specified class. The new component will be added to the collection so the same instance can be retrieved later.

If creating a default instance fails and a default value is specified, it will return that default value and also add it to the collection. If no default value is specified, it throws a runtime exception.

Type Parameters:

T - the type of component

Parameters:

clazz - the component class

defaultVal - the default value to return if there is no component of the specified class and no default instance can be created. Set this to null if you want a runtime exception in that case.

Returns:

the component

Throws:

RuntimeException - if a default instance cannot be created and no default value is specified