Class XmlLoader
For a description of the XML file format this class can load see the BASE manual.
Factory initialisation
This loader uses reflection to create and initialise factory
instances. The XML file contains the class name of the factory
to create. This class must declare a public no-argument
constructor and must also implement one of the specific
factory interfaces (for example ActionFactory
or RendererFactory
). If the tag <parameters>
is present inside the factory declaration, the loader will
use reflection to find a setter method for each sub-tag inside
the <parameters>
tag. Here is an example:
// XML contents <parameters> <image>button.png</image> <title>Click button</title> </parameters> // Factory initialization factory.setImage("button.png"); factory.setTitle("Click button");The setter methods must be public and accept a single
String
parameter.
The loader also looks for the setParameter(String, String)
method signature. If the method exists it will be called for each
parameter found with the tagname as the first parameter and the
value as the second parameter. Continuing the above example:
factory.setParameter("image", "button.png"); factory.setParameter("title", "Click button");
Tags that doesn't have a corresponding setter method are simply ignored. The XML file format allows any tags as parameters, but only the first level will be parsed.
The parameter values may be subject to conversion by one or more
ValueConverter
:s. Converters are added to the loader
by addValueConverter(ValueConverter)
and are usually
implemented to react on method annotations. For example, the web
client uses this for path and variable substitution.
- Version:
- 2.7
- Author:
- nicklas
- Last modified
- $Date:2008-03-20 12:15:25 +0100 (Thu, 20 Mar 2008) $
-
Field Summary
Modifier and TypeFieldDescriptionprivate final Map<String,
ClassLoader> private Set<ValueConverter>
private final List<ExtensionPoint<Action>>
private String
private static final Logger
static final String
The name of the extensions namespace.private final List<PluginInfo>
static final String
The URL pointing to the extensions.xsd schema.private Document
private XMLOutputter
-
Constructor Summary
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addValueConverter
(ValueConverter converter) Add a value converter to this loadervoid
Remove all value converters.protected <F> F
createFactory
(Element factoryTag, ClassLoader classLoader, Class<F> factoryType, Presets.Preset config) Create a new factory instance.protected String
getConvertedValue
(String original, Method method) Get a list with all loaded extension points.Get a list with all loaded extensions.getFactoryParameters
(Object factory) Get a XML-like string representation of the parameters that was used to initialise a factory.Get a list with all loaded plug-in definitions.protected Method
getSetParameterMethod
(Class<?> beanClass) Check if the bean class has asetParameter(String, String)
method and return it's reference if it has.protected Method
getSetterMethod
(Class<?> beanClass, String tagName) Get the setter method for a given tag name.protected String
getSetterMethodNameFromTag
(String tagName) Convert the tag name to a setter method name.boolean
Checks if an XML file has passed validation in thevalidateXmlFile(InputStream, String)
method.protected void
initBeanWithReflection
(Object bean, Element root, Presets.Preset config) Initialise a bean using reflection.protected AboutBean
Load information in an<about>
tag.protected Document
loadDocument
(InputStream xmlFile, String filename) Load and validate the XML file.protected int
loadExtensionPoints
(Document dom, ClassLoader classLoader, About globalAbout) Create extension points from an XML document.protected int
loadExtensions
(Document dom, ClassLoader classLoader, About globalAbout) Create extensions from an XML document.protected AboutBean
loadGlobalAbout
(Document dom) Load the global about tag from the document.loadLastValidatedFile
(ClassLoader classLoader, boolean clear) Continue loading extensions from the last validated XML file.protected int
loadPluginDefinitions
(Document dom, ClassLoader classLoader, About globalAbout) Load plug-in information from an XML document.loadXmlFile
(InputStream xmlFile, String filename, ClassLoader classLoader, boolean clear) Load an extensions definition XML file.int
registerExtensionPoints
(Registry registry, boolean update) Register all loaded extension points with a registry.int
registerExtensions
(Registry registry, boolean update) Register all loaded extensions with a registry.void
removeValueConverter
(ValueConverter converter) Remove a converter.void
Set a filter that all <extension-point>, <extension>, <ref> and <plugin-definition> tags must pass to be loaded and registered.int
unregisterExtensionPoints
(Registry registry) Unregister all loaded extension points from a registry.int
unregisterExtensions
(Registry registry) Unregister all loaded extensions from a registry.validateXmlFile
(InputStream xmlFile, String filename) Validate an XML file against the extensions definition schema.protected boolean
verifyBaseVersion
(About about, boolean throwException)
-
Field Details
-
log
-
SCHEMA_FILE_URL
The URL pointing to the extensions.xsd schema. -
NAMESPACE
The name of the extensions namespace.- See Also:
-
xmlOut
-
extensionPoints
-
extensions
-
pluginDefinitions
-
converters
-
factoryParameters
-
classLoaders
-
validatedDom
-
lastName
-
filter
-
-
Constructor Details
-
XmlLoader
public XmlLoader()Create a new XML loader instance.
-
-
Method Details
-
addValueConverter
Add a value converter to this loader- Parameters:
converter
- The converter to add- Throws:
NullPointerException
- If the converter is null
-
removeValueConverter
Remove a converter.- Parameters:
converter
- The converter to remove, null values are ignored
-
clearValueConverters
public void clearValueConverters()Remove all value converters. -
setFilter
Set a filter that all <extension-point>, <extension>, <ref> and <plugin-definition> tags must pass to be loaded and registered.- Parameters:
filter
- A filter or null to remove an existing filter- Since:
- 3.0
-
loadXmlFile
public About loadXmlFile(InputStream xmlFile, String filename, ClassLoader classLoader, boolean clear) throws IOException, ClassNotFoundException, NoSuchMethodException, IllegalAccessException, InstantiationException, InvocationTargetException Load an extensions definition XML file. This method may be called multiple times with different XML files. The loading may also be done by a two-step process where the first step validates the file and the second step loads the extensions. SeevalidateXmlFile(InputStream, String)
andloadLastValidatedFile(ClassLoader, boolean)
.- Parameters:
xmlFile
- An input stream to read the XML data fromfilename
- The original filename the stream is coming from, or null if not known. This value is only used when generating error messagesclassLoader
- The classloader to use when loading classes that are named in the XML file, or null to use the default classloader (=the same class loader that loaded the BASE core classes)clear
- TRUE to clear all already loaded extensions before loading the extensions in this file- Returns:
- Information about the extension, or null if no such information is available
- Throws:
IOException
- If there is an error reading the XML fileClassNotFoundException
- If a class named in the XML file can't be foundNoSuchMethodException
- If a factory class doesn't implement a public, no-argument constructorIllegalAccessException
- If a factory class constructor isn't publicInstantiationException
- If a factory class can't be instantiated, for example, because it is an abstract class or an interfaceInvocationTargetException
- See Also:
-
validateXmlFile
Validate an XML file against the extensions definition schema. If the file is valid you may continue to load the extensions. SeeloadLastValidatedFile(ClassLoader, boolean)
.- Parameters:
xmlFile
- An input stream to read the XML data fromfilename
- The original filename the stream is coming from, or null if not known. This value is only used when generating error messages- Returns:
- Information about the extension, or null if no such information is available
- Throws:
IOException
- If there is an error reading the XML file
-
loadLastValidatedFile
public About loadLastValidatedFile(ClassLoader classLoader, boolean clear) throws ClassNotFoundException, IllegalAccessException, InstantiationException, NoSuchMethodException, InvocationTargetException Continue loading extensions from the last validated XML file. This is the second step in a two-step process and requires thatvalidateXmlFile(InputStream, String)
has been successfully called first.- Parameters:
classLoader
- The classloader to use when loading classes that are named in the XML file, or null to use the default classloader (=the same class loader that loaded the BASE core classes)clear
- TRUE to clear all already loaded extensions before loading the extensions in this file- Returns:
- Information about the extension, or null if no such information is available
- Throws:
ClassNotFoundException
- If a class named in the XML file can't be foundNoSuchMethodException
- If a factory class doesn't implement a public, no-argument constructorIllegalAccessException
- If a factory class constructor isn't publicInstantiationException
- If a factory class can't be instantiated, for example, because it is an abstract class or an interfaceInvocationTargetException
-
hasValidFile
public boolean hasValidFile()Checks if an XML file has passed validation in thevalidateXmlFile(InputStream, String)
method. If so, theloadLastValidatedFile(ClassLoader, boolean)
can be called to continue loading the extensions.Note that once the file has been loaded this flag is reset to FALSE.
- Returns:
- TRUE if a file has been validated, FALSE otherwise
-
getExtensionPoints
Get a list with all loaded extension points. -
getExtensions
Get a list with all loaded extensions. -
getPluginDefinitions
Get a list with all loaded plug-in definitions.- Since:
- 3.0
-
getFactoryParameters
Get a XML-like string representation of the parameters that was used to initialise a factory.- Parameters:
factory
- The factory object- Returns:
- The parameters as found in the XML file
-
registerExtensionPoints
Register all loaded extension points with a registry.- Parameters:
registry
- The registryupdate
- TRUE to update already registered extension points, FALSE to ignore- Returns:
- The number of extension points registered or updated
- See Also:
-
unregisterExtensionPoints
Unregister all loaded extension points from a registry. All extensions will also be unregistered.- Parameters:
registry
- The registry- Returns:
- The number of extension points that was unregistered
- See Also:
-
registerExtensions
Register all loaded extensions with a registry.- Parameters:
registry
- The registryupdate
- TRUE to update already registered extensions FALSE to ignore- Returns:
- The number of registered or updated extensions
- See Also:
-
unregisterExtensions
Unregister all loaded extensions from a registry.- Parameters:
registry
- The registry- Returns:
- The number of extensions that was unregistered
- See Also:
-
loadDocument
Load and validate the XML file.- Returns:
- A JDOM document object
- Throws:
IOException
-
verifyBaseVersion
-
loadGlobalAbout
Load the global about tag from the document.- Returns:
- An about bean or null if the about tag is not found.
-
loadAbout
Load information in an<about>
tag.- Parameters:
aboutTag
- The about tag
-
loadExtensionPoints
protected int loadExtensionPoints(Document dom, ClassLoader classLoader, About globalAbout) throws ClassNotFoundException, NoSuchMethodException, IllegalAccessException, InstantiationException, InvocationTargetException Create extension points from an XML document. -
loadExtensions
protected int loadExtensions(Document dom, ClassLoader classLoader, About globalAbout) throws ClassNotFoundException, NoSuchMethodException, IllegalAccessException, InstantiationException, InvocationTargetException Create extensions from an XML document. -
loadPluginDefinitions
protected int loadPluginDefinitions(Document dom, ClassLoader classLoader, About globalAbout) throws ClassNotFoundException, NoSuchMethodException, IllegalAccessException, InstantiationException Load plug-in information from an XML document.- Throws:
ClassNotFoundException
NoSuchMethodException
IllegalAccessException
InstantiationException
- Since:
- 3.0
-
createFactory
protected <F> F createFactory(Element factoryTag, ClassLoader classLoader, Class<F> factoryType, Presets.Preset config) throws ClassNotFoundException, NoSuchMethodException, IllegalAccessException, InstantiationException, InvocationTargetException Create a new factory instance. The factory must be a class with a public, no-argument constructor. The factory class name is read from the <factory-class> tag and initialisation parameters from the <parameters> tag.- Parameters:
factoryTag
- The root tag of the factory definitionclassLoader
- The classloader to use, or null to use the BASE core classloaderfactoryType
- Class type of the factory. The named class must implement or be a subclass of this class- Returns:
- An initialised factory
- Throws:
ClassNotFoundException
NoSuchMethodException
IllegalAccessException
InstantiationException
InvocationTargetException
-
initBeanWithReflection
Initialise a bean using reflection. For each child tag of the 'root' element, this method will check if the bean implements a setter method that is compatible with the child tag name. The method name should start with 'set' and then the tag name with the first letter capitalized. The method must take a single String argument. For example, if there is a child tag<image>button.png</image>
this will be converted to the method call:setImage("button.png")
.Tags that has no matching public setter method are ignored.
- Parameters:
bean
- The bean to initializeroot
- The root element, if null nothing is done
-
getSetterMethod
Get the setter method for a given tag name.- Parameters:
beanClass
- The class to look for the setter method intagName
- The tag name in the XML file- Returns:
- A Method object, or null if no method is found
-
getSetParameterMethod
Check if the bean class has asetParameter(String, String)
method and return it's reference if it has.- Parameters:
beanClass
- The class to look for the method in- Returns:
- A Method object, or null if no method is found
-
getSetterMethodNameFromTag
Convert the tag name to a setter method name. The tag name is prefixed with 'set', the first letter is capitalized, hyphens in the tag name are removed and the first letter after each is capitalized.- Parameters:
tagName
- The tag name- Returns:
- The converted tag name
-
getConvertedValue
-