org.jvnet.hk2.config
Class Dom

java.lang.Object
  com.sun.hk2.component.AbstractInhabitantImpl<T>
      com.sun.hk2.component.EventPublishingInhabitant<T>
          com.sun.hk2.component.LazyInhabitant
              org.jvnet.hk2.config.Dom

All Implemented Interfaces:

com.sun.hk2.component.ClassLoaderHolder, com.sun.hk2.component.Holder, java.lang.reflect.InvocationHandler, org.jvnet.hk2.component.Inhabitant, ObservableBean

Direct Known Subclasses:

ConfigBean

public class Dom
extends com.sun.hk2.component.LazyInhabitant
implements java.lang.reflect.InvocationHandler, ObservableBean

Inhabitant that loads configuration from XML.

This object also captures all the configuration values in a typeless way, so that the loading of the actual classes can be deferred as much as possible.

This is the Inhabitant that gets registered into Habitat, so one can access this object by Habitat.getInhabitant(Class, String) family of methods.

Author:

Kohsuke Kawaguchi

Nested Class Summary

Nested classes/interfaces inherited from interface com.sun.hk2.component.Holder

com.sun.hk2.component.Holder.Impl<T>

Field Summary

DomDocument	document Owner of the DOM tree.
ConfigModel	model Model drives the interpretation of this DOM.

Fields inherited from class com.sun.hk2.component.LazyInhabitant

habitat

Fields inherited from class com.sun.hk2.component.EventPublishingInhabitant

real

Constructor Summary

Dom(Dom source, Dom parent)
Copy constructor, used to get a deep copy of the passed instance

Dom(org.jvnet.hk2.component.Habitat habitat, DomDocument document, Dom parent, ConfigModel model)

Dom(org.jvnet.hk2.component.Habitat habitat, DomDocument document, Dom parent, ConfigModel model, javax.xml.stream.XMLStreamReader in)

Method Summary

void	addDefaultChildren() When a new Dom object is created, ensures that all @NotNull annotated elements have a value.
boolean	addLeafElement(java.lang.String xmlName, java.lang.String value)
void	addListener(ConfigListener listener) Add a new listener to configuration changes.
java.lang.String	attribute(java.lang.String name) Obtains the attribute value, after variable expansion.
void	attribute(java.lang.String name, java.lang.String value) Updates the attribute value.
java.util.List<java.lang.String>	attributes(java.lang.String name) Obtains the plural attribute value.
boolean	changeLeafElement(java.lang.String xmlName, java.lang.String oldValue, java.lang.String newValue)
static java.lang.String	convertName(java.lang.String name)
protected <T extends Dom> T	copy(T parent) Returns a copy of itself providing the parent for the new copy.
protected org.jvnet.hk2.component.Creator	createCreator(java.lang.Class c) This is how we inject the configuration into the created object.
<T extends ConfigBeanProxy> T	createProxy() Creates a strongly-typed proxy to access values in this Dom object,
<T extends ConfigBeanProxy> T	createProxy(java.lang.Class<T> proxyType) Creates a strongly-typed proxy to access values in this Dom object, by using the specified interface type as the proxy type.
static <T extends java.lang.annotation.Annotation> T	digAnnotation(java.lang.Class<?> target, java.lang.Class<T> annotationType)
static <T extends java.lang.annotation.Annotation> T	digAnnotation(java.lang.Class<?> target, java.lang.Class<T> annotationType, java.util.List<java.lang.Class<? extends java.lang.annotation.Annotation>> visited)
java.util.List<Dom>	domNodeByTypeElements(java.lang.Class baseType) Picks up all node elements that are assignable to the given type, except those who are matched by other named elements in the model.
Dom	element(java.lang.String name) Returns the child element by name
java.util.Set<java.lang.String>	getAttributeNames() Returns the list of attributes with a value on this config instance.
java.util.Set<java.lang.String>	getElementNames() Returns the children name associated with this config instance.
org.jvnet.hk2.component.Habitat	getHabitat()
ConfigInjector	getInjector() Gets the ConfigInjector instance that can be used to inject this DOM to a bean.
java.lang.String	getKey() Obtains the actual key value from this Dom.
javax.xml.stream.Location	getLocation() Where was this Dom loaded from?
<T extends ConfigBeanProxy> java.lang.Class<T>	getProxyType() Returns the proxy type for this configuration object
Dom	getSymbolSpaceRoot(java.lang.String typeName) Locates the DOM that serves as the symbol space root.
protected java.lang.Object	getter(ConfigModel.Property target, java.lang.reflect.Type t)
void	initializationCompleted()
void	inject(java.lang.Object target) Performs injection to the given object.
protected void	injectInto(Dom injectable, java.lang.Object target)
void	insertAfter(Dom reference, java.lang.String name, Dom newNode) Inserts a new Dom node right after the given DOM element.
java.lang.Object	invoke(java.lang.Object proxy, java.lang.reflect.Method method, java.lang.Object[] args) InvocationHandler implementation that allows strongly-typed access to the configuration.
java.lang.Object	invoke(java.lang.Object proxy, java.lang.String methodName, java.lang.Class[] argTypes, java.lang.Object[] args) Another version of the invoke(Object, Method, Object[]), but instead of Method object, it takes the method name and argument types.
java.lang.String	leafElement(java.lang.String name) Picks up one leaf-element value.
java.util.List<java.lang.String>	leafElements(java.lang.String name) Picks up all leaf-element values of the given name.
<T> T	nodeByTypeElement(java.lang.Class<T> baseType)
<T> java.util.List<T>	nodeByTypeElements(java.lang.Class<T> baseType)
Dom	nodeElement(java.lang.String name) Picks up one node-element value.
java.util.List<Dom>	nodeElements(java.lang.String elementName) Picks up all node-elements that have the given element name.
Dom	parent() If this DOM is a child of another DOM, the parent pointer.
java.lang.String	rawAttribute(java.lang.String name) Obtians the attribute value without variable expansion.
java.lang.String	rawLeafElement(java.lang.String name) Picks up one leaf-element value without variable expansion.
java.util.List<java.lang.String>	rawLeafElements(java.lang.String name) Picks up all leaf-element values of the given name, without variable expansion.
void	release()
void	removeChild(Dom reference) Removes an existing NodeChild
boolean	removeLeafElement(java.lang.String xmlName, java.lang.String element)
boolean	removeListener(ConfigListener listener) Remove a listener
void	replaceChild(Dom reference, java.lang.String name, Dom newNode) Replaces an existing NodeChild with another one.
Dom	resolveReference(java.lang.String key, java.lang.String typeName) Recursively decends the DOM tree and finds a DOM that has the given key and the type name.
void	setLeafElements(java.lang.String name, java.lang.String... values) Updates leaf-element values.
void	setNodeElements(java.lang.String name, Dom... values) Updates node-element values.
protected void	setter(ConfigModel.Property target, java.lang.Object value)
static Dom	unwrap(ConfigBeanProxy proxy) Unwraps the proxy and returns the underlying Dom object.
void	writeTo(java.lang.String tagName, javax.xml.stream.XMLStreamWriter w) Writes back this element.

Methods inherited from class com.sun.hk2.component.LazyInhabitant

fetch, getClassLoader, lead, loadClass, metadata, type, typeName

Methods inherited from class com.sun.hk2.component.EventPublishingInhabitant

addInhabitantListener, get, isInstantiated, notify, removeInhabitantListener, toString

Methods inherited from class com.sun.hk2.component.AbstractInhabitantImpl

companions, get, getAnnotation, getAnnotation, getSerializedMetadata, getSerializedMetadata, setCompanions

Methods inherited from class java.lang.Object

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

Field Detail

model

public final ConfigModel model

Model drives the interpretation of this DOM.

document

public final DomDocument document

Owner of the DOM tree.

Constructor Detail

Dom

public Dom(org.jvnet.hk2.component.Habitat habitat,
           DomDocument document,
           Dom parent,
           ConfigModel model,
           javax.xml.stream.XMLStreamReader in)

Parameters:

in - If provided, this is used to record the source location where this DOM object is loaded from. Otherwise this can be null.

Dom

public Dom(org.jvnet.hk2.component.Habitat habitat,
           DomDocument document,
           Dom parent,
           ConfigModel model)

Dom

public Dom(Dom source,
           Dom parent)

Copy constructor, used to get a deep copy of the passed instance

Parameters:

source - the instance to copy

Method Detail

initializationCompleted

public void initializationCompleted()

addDefaultChildren

public void addDefaultChildren()

When a new Dom object is created, ensures that all @NotNull annotated elements have a value.

copy

protected <T extends Dom> T copy(T parent)

Returns a copy of itself providing the parent for the new copy.

Parameters:

parent - the parent instance for the cloned copy

Returns:

the cloned copy

unwrap

public static Dom unwrap(ConfigBeanProxy proxy)

Unwraps the proxy and returns the underlying Dom object.

Returns:

null if the given instance is not actually a proxy to a DOM.

getKey

public java.lang.String getKey()

Obtains the actual key value from this Dom.

parent

public Dom parent()

If this DOM is a child of another DOM, the parent pointer. Otherwise null.

getLocation

public javax.xml.stream.Location getLocation()

Where was this Dom loaded from?

getAttributeNames

public java.util.Set<java.lang.String> getAttributeNames()

Returns the list of attributes with a value on this config instance. This is by definition a subset of the attributes names as known to the model ConfigModel.getAttributeNames.

Returns:

list of attributes names which have values on this config instance

getElementNames

public java.util.Set<java.lang.String> getElementNames()

Returns the children name associated with this config instance. This is by definition a subset of the element names as known to the model {#see ConfigModel.getElementNames().

attribute

public java.lang.String attribute(java.lang.String name)

Obtains the attribute value, after variable expansion.

Returns:

null if the attribute is not found.

rawAttribute

public java.lang.String rawAttribute(java.lang.String name)

Obtians the attribute value without variable expansion.

Returns:

null if the attribute is not found.

attributes

public java.util.List<java.lang.String> attributes(java.lang.String name)

Obtains the plural attribute value. Values are separate by ',' and surrounding whitespaces are ignored.

Returns:

null if the attribute doesn't exist. This is a distinct state from the empty list, which indicates that the attribute was there but no values were found.

attribute

public void attribute(java.lang.String name,
                      java.lang.String value)

Updates the attribute value. This would trigger the re-injection of the value.

element

public Dom element(java.lang.String name)

Returns the child element by name

Parameters:

name - of the element

Returns:

child element

leafElement

public java.lang.String leafElement(java.lang.String name)

Picks up one leaf-element value.

insertAfter

public void insertAfter(Dom reference,
                        java.lang.String name,
                        Dom newNode)

Inserts a new Dom node right after the given DOM element.

Parameters:

reference - If null, the new element will be inserted at the very beginning.

name - The element name of the newly inserted item. "*" to indicate that the element name be determined by the model of the new node.

replaceChild

public void replaceChild(Dom reference,
                         java.lang.String name,
                         Dom newNode)

Replaces an existing NodeChild with another one.

See Also:

insertAfter(Dom, String, Dom)

removeChild

public void removeChild(Dom reference)

Removes an existing NodeChild

addLeafElement

public boolean addLeafElement(java.lang.String xmlName,
                              java.lang.String value)

removeLeafElement

public boolean removeLeafElement(java.lang.String xmlName,
                                 java.lang.String element)

changeLeafElement

public boolean changeLeafElement(java.lang.String xmlName,
                                 java.lang.String oldValue,
                                 java.lang.String newValue)

rawLeafElement

public java.lang.String rawLeafElement(java.lang.String name)

Picks up one leaf-element value without variable expansion.

setLeafElements

public void setLeafElements(java.lang.String name,
                            java.lang.String... values)

Updates leaf-element values.

Synchronized so that concurrenct modifications will work correctly.

leafElements

public java.util.List<java.lang.String> leafElements(java.lang.String name)

Picks up all leaf-element values of the given name.

Returns:

Can be empty but never null.

rawLeafElements

public java.util.List<java.lang.String> rawLeafElements(java.lang.String name)

Picks up all leaf-element values of the given name, without variable expansion.

Returns:

can be empty, but never null (even if such element name is not defined in the model.)

nodeElement

public Dom nodeElement(java.lang.String name)

Picks up one node-element value.

setNodeElements

public void setNodeElements(java.lang.String name,
                            Dom... values)

Updates node-element values.

Synchronized so that concurrenct modifications will work correctly.

nodeElements

public java.util.List<Dom> nodeElements(java.lang.String elementName)

Picks up all node-elements that have the given element name.

domNodeByTypeElements

public java.util.List<Dom> domNodeByTypeElements(java.lang.Class baseType)

Picks up all node elements that are assignable to the given type, except those who are matched by other named elements in the model. Used to implement FromElement("*").

nodeByTypeElements

public <T> java.util.List<T> nodeByTypeElements(java.lang.Class<T> baseType)

nodeByTypeElement

public <T> T nodeByTypeElement(java.lang.Class<T> baseType)

inject

public void inject(java.lang.Object target)

Performs injection to the given object.

getInjector

public ConfigInjector getInjector()

Gets the ConfigInjector instance that can be used to inject this DOM to a bean.

getSymbolSpaceRoot

public Dom getSymbolSpaceRoot(java.lang.String typeName)

Locates the DOM that serves as the symbol space root.

Returns:

always non-null.

resolveReference

public Dom resolveReference(java.lang.String key,
                            java.lang.String typeName)

Recursively decends the DOM tree and finds a DOM that has the given key and the type name.

TODO: the current algorithm does a full tree scan. Expand the model so that we can detect deadends that are statically known not to contain the kind we are looking for, and use that to cut the search space.

createProxy

public <T extends ConfigBeanProxy> T createProxy(java.lang.Class<T> proxyType)

Creates a strongly-typed proxy to access values in this Dom object, by using the specified interface type as the proxy type.

createProxy

public <T extends ConfigBeanProxy> T createProxy()

Creates a strongly-typed proxy to access values in this Dom object,

getProxyType

public <T extends ConfigBeanProxy> java.lang.Class<T> getProxyType()

Returns the proxy type for this configuration object

Type Parameters:

T - the proxy type

Returns:

the class object for the proxy type

invoke

public java.lang.Object invoke(java.lang.Object proxy,
                               java.lang.reflect.Method method,
                               java.lang.Object[] args)
                        throws java.lang.Throwable

InvocationHandler implementation that allows strongly-typed access to the configuration.

TODO: it might be a great performance improvement to have APT generate code that does this during the development time by looking at the interface.

Specified by:

invoke in interface java.lang.reflect.InvocationHandler

Throws:

java.lang.Throwable

getHabitat

public org.jvnet.hk2.component.Habitat getHabitat()

invoke

public java.lang.Object invoke(java.lang.Object proxy,
                               java.lang.String methodName,
                               java.lang.Class[] argTypes,
                               java.lang.Object[] args)
                        throws java.lang.Throwable

Another version of the invoke(Object, Method, Object[]), but instead of Method object, it takes the method name and argument types.

Throws:

java.lang.Throwable

getter

protected java.lang.Object getter(ConfigModel.Property target,
                                  java.lang.reflect.Type t)

setter

protected void setter(ConfigModel.Property target,
                      java.lang.Object value)
               throws java.lang.Exception

Throws:

java.lang.Exception

convertName

public static java.lang.String convertName(java.lang.String name)

createCreator

protected org.jvnet.hk2.component.Creator createCreator(java.lang.Class c)

This is how we inject the configuration into the created object.

There are two kinds — one where @Configured is put on a bean and that is placedinto Habitat, and the other is where @Configured is on ConfigBeanProxy subtype, in which case the proxy to Dom will be placed into the habitat.

Overrides:

createCreator in class com.sun.hk2.component.LazyInhabitant

digAnnotation

public static <T extends java.lang.annotation.Annotation> T digAnnotation(java.lang.Class<?> target,
                                                                          java.lang.Class<T> annotationType)

digAnnotation

public static <T extends java.lang.annotation.Annotation> T digAnnotation(java.lang.Class<?> target,
                                                                          java.lang.Class<T> annotationType,
                                                                          java.util.List<java.lang.Class<? extends java.lang.annotation.Annotation>> visited)

writeTo

public void writeTo(java.lang.String tagName,
                    javax.xml.stream.XMLStreamWriter w)
             throws javax.xml.stream.XMLStreamException

Writes back this element.

Parameters:

tagName - The tag name of this element to be written. If null, this DOM node must be a global element and its tag name will be used.

w - Receives XML infoset stream.

Throws:

javax.xml.stream.XMLStreamException

injectInto

protected void injectInto(Dom injectable,
                          java.lang.Object target)

release

public void release()

Specified by:

release in interface org.jvnet.hk2.component.Inhabitant

Overrides:

release in class com.sun.hk2.component.LazyInhabitant

addListener

public void addListener(ConfigListener listener)

Description copied from interface: ObservableBean

Add a new listener to configuration changes.

Specified by:

addListener in interface ObservableBean

Parameters:

listener - new listener

removeListener

public boolean removeListener(ConfigListener listener)

Description copied from interface: ObservableBean

Remove a listener

Specified by:

removeListener in interface ObservableBean

Parameters:

listener - to remove

Returns:

true if listener removal was successful.