Package org.jvnet.hk2.config

Class Dom

java.lang.Object

org.glassfish.hk2.utilities.DescriptorImpl

org.glassfish.hk2.utilities.AbstractActiveDescriptor

org.jvnet.hk2.config.Dom

All Implemented Interfaces:

Externalizable, Serializable, InvocationHandler, org.glassfish.hk2.api.ActiveDescriptor, org.glassfish.hk2.api.Descriptor, org.glassfish.hk2.api.SingleCache, ObservableBean

Direct Known Subclasses:

ConfigBean

public class Dom
extends org.glassfish.hk2.utilities.AbstractActiveDescriptor
implements InvocationHandler, ObservableBean

InvocationHandler 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 ActiveDescriptor that gets registered into ServiceLocator, so one can access this object by ServiceLocator.getServiceHandle(Class, String, Annotation...) family of methods.

Author:

Kohsuke Kawaguchi

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
final DomDocument	document	Owner of the DOM tree.
final ConfigModel	model	Model drives the interpretation of this DOM.

Constructor Summary

Constructors

Constructor	Description
Dom(org.glassfish.hk2.api.ServiceLocator habitat, DomDocument document, Dom parent, ConfigModel model)
Dom(org.glassfish.hk2.api.ServiceLocator habitat, DomDocument document, Dom parent, ConfigModel model, XMLStreamReader in)
Dom(Dom source, Dom parent)	Copy constructor, used to get a deep copy of the passed instance

Method Summary

Modifier and Type	Method	Description
void	addDefaultChildren()	When a new Dom object is created, ensures that all @NotNull annotated elements have a value.
boolean	addLeafElement(String xmlName, String value)
void	addListener(ConfigListener listener)	Add a new listener to configuration changes.
String	attribute(String name)	Obtains the attribute value, after variable expansion.
void	attribute(String name, String value)	Updates the attribute value.
List<String>	attributes(String name)	Obtains the plural attribute value.
boolean	changeLeafElement(String xmlName, String oldValue, String newValue)
static String	convertName(String name)
protected <T extends Dom> T	copy(T parent)	Returns a copy of itself providing the parent for the new copy.
Object	create(org.glassfish.hk2.api.ServiceHandle root)
protected Creator	createCreator(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(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 Annotation> T	digAnnotation(Class<?> target, Class<T> annotationType)
static <T extends Annotation> T	digAnnotation(Class<?> target, Class<T> annotationType, List<Class<? extends Annotation>> visited)
List<Dom>	domNodeByTypeElements(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(String name)	Returns the child element by name
boolean	equals(Object o)
Object	get()
Set<String>	getAttributeNames()	Returns the list of attributes with a value on this config instance.
Object	getCache()
Set<Type>	getContractTypes()
Set<String>	getElementNames()	Returns the children name associated with this config instance.
Long	getFactoryLocatorId()
Long	getFactoryServiceId()
org.glassfish.hk2.api.ServiceLocator	getHabitat()
Class<?>	getImplementationClass()
Type	getImplementationType()
List<org.glassfish.hk2.api.Injectee>	getInjectees()
ConfigInjector	getInjector()	Gets the ConfigInjector instance that can be used to inject this DOM to a bean.
String	getKey()	Obtains the actual key value from this Dom.
Location	getLocation()	Where was this Dom loaded from?
<T extends ConfigBeanProxy> Class<T>	getProxyType()	Returns the proxy type for this configuration object
Set<Annotation>	getQualifierAnnotations()
Class<? extends Annotation>	getScopeAnnotation()
org.glassfish.hk2.api.ServiceLocator	getServiceLocator()
Dom	getSymbolSpaceRoot(String typeName)	Locates the DOM that serves as the symbol space root.
protected Object	getter(ConfigModel.Property target, Type t)
int	hashCode()
void	initializationCompleted()
void	inject(Object target)	Performs injection to the given object.
void	insertAfter(Dom reference, String name, Dom newNode)	Inserts a new Dom node right after the given DOM element.
Object	invoke(Object proxy, Method method, Object[] args)	InvocationHandler implementation that allows strongly-typed access to the configuration.
Object	invoke(Object proxy, String methodName, Class[] argTypes, Object[] args)	Another version of the invoke(Object, Method, Object[]), but instead of Method object, it takes the method name and argument types.
boolean	isCacheSet()
boolean	isReified()	This ensures no-one tried to reify this descriptor, which has an impl class the interface
String	leafElement(String name)	Picks up one leaf-element value.
List<String>	leafElements(String name)	Picks up all leaf-element values of the given name.
<T> T	nodeByTypeElement(Class<T> baseType)
<T> List<T>	nodeByTypeElements(Class<T> baseType)
Dom	nodeElement(String name)	Picks up one node-element value.
List<Dom>	nodeElements(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.
String	rawAttribute(String name)	Obtians the attribute value without variable expansion.
String	rawLeafElement(String name)	Picks up one leaf-element value without variable expansion.
List<String>	rawLeafElements(String name)	Picks up all leaf-element values of the given name, without variable expansion.
void	release()
void	releaseCache()
void	removeChild(Dom reference)	Removes an existing Dom.NodeChild
boolean	removeLeafElement(String xmlName, String element)
boolean	removeListener(ConfigListener listener)	Remove a listener
void	replaceChild(Dom reference, String name, Dom newNode)	Replaces an existing Dom.NodeChild with another one.
Dom	resolveReference(String key, String typeName)	Recursively decends the DOM tree and finds a DOM that has the given key and the type name.
void	setCache(Object cacheMe)
void	setImplementationType(Type t)
void	setLeafElements(String name, String... values)	Updates leaf-element values.
void	setNodeElements(String name, Dom... values)	Updates node-element values.
protected void	setter(ConfigModel.Property target, Object value)
void	skipFromXml()	This method should be invoked if this Dom should not be persisted to the domain.xml file.
static Dom	unwrap(ConfigBeanProxy proxy)	Unwraps the proxy and returns the underlying Dom object.
void	writeTo(String tagName, XMLStreamWriter w)	Writes back this element.
void	writeToXml()	This method should be invoked if this Dom needs to be persisted to domain.xml file

Methods inherited from class org.glassfish.hk2.utilities.AbstractActiveDescriptor

addContractType, addQualifierAnnotation, dispose, getScopeAsAnnotation, removeContractType, removeQualifierAnnotation, setFactoryId, setName, setReified, setScopeAnnotation, setScopeAsAnnotation

Methods inherited from class org.glassfish.hk2.utilities.DescriptorImpl

addAdvertisedContract, addMetadata, addMetadata, addQualifier, clearMetadata, descriptorEquals, getAdvertisedContracts, getClassAnalysisName, getDescriptorType, getDescriptorVisibility, getImplementation, getLoader, getLocatorId, getMetadata, getName, getQualifiers, getRanking, getScope, getServiceId, isProxiable, isProxyForSameScope, pretty, readExternal, readObject, removeAdvertisedContract, removeAllMetadata, removeMetadata, removeQualifier, setClassAnalysisName, setDescriptorType, setDescriptorVisibility, setImplementation, setLoader, setLocatorId, setMetadata, setProxiable, setProxyForSameScope, setRanking, setScope, setServiceId, toString, writeExternal, writeObject

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.glassfish.hk2.api.Descriptor

getAdvertisedContracts, getClassAnalysisName, getDescriptorType, getDescriptorVisibility, getImplementation, getLoader, getLocatorId, getMetadata, getName, getQualifiers, getRanking, getScope, getServiceId, isProxiable, isProxyForSameScope, setRanking

Field Details

model

public final ConfigModel model

Model drives the interpretation of this DOM.

document

public final DomDocument document

Owner of the DOM tree.

Constructor Details

Dom

public Dom(org.glassfish.hk2.api.ServiceLocator habitat,
 DomDocument document,
 Dom parent,
 ConfigModel model,
 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.glassfish.hk2.api.ServiceLocator 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 Details

skipFromXml

public void skipFromXml()

This method should be invoked if this Dom should not be persisted to the domain.xml file.

writeToXml

public void writeToXml()

This method should be invoked if this Dom needs to be persisted to domain.xml file

initializationCompleted

public void initializationCompleted()

addDefaultChildren

public void addDefaultChildren()

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

getHabitat

public org.glassfish.hk2.api.ServiceLocator getHabitat()

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 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 Location getLocation()

Where was this Dom loaded from?

getAttributeNames

public Set<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 .

Returns:

list of attributes names which have values on this config instance

getElementNames

public Set<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 String attribute(String name)

Obtains the attribute value, after variable expansion.

Returns:

null if the attribute is not found.

rawAttribute

public String rawAttribute(String name)

Obtians the attribute value without variable expansion.

Returns:

null if the attribute is not found.

attributes

public List<String> attributes(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(String name,
 String value)

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

element

public Dom element(String name)

Returns the child element by name

Parameters:

name - of the element

Returns:

child element

leafElement

public String leafElement(String name)

Picks up one leaf-element value.

insertAfter

public void insertAfter(Dom reference,
 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,
 String name,
 Dom newNode)

Replaces an existing Dom.NodeChild with another one.

See Also:

• insertAfter(Dom, String, Dom)

removeChild

public void removeChild(Dom reference)

Removes an existing Dom.NodeChild

addLeafElement

public boolean addLeafElement(String xmlName,
 String value)

removeLeafElement

public boolean removeLeafElement(String xmlName,
 String element)

changeLeafElement

public boolean changeLeafElement(String xmlName,
 String oldValue,
 String newValue)

rawLeafElement

public String rawLeafElement(String name)

Picks up one leaf-element value without variable expansion.

setLeafElements

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

Updates leaf-element values.

Synchronized so that concurrenct modifications will work correctly.

leafElements

public List<String> leafElements(String name)

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

Returns:

Can be empty but never null.

rawLeafElements

public List<String> rawLeafElements(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(String name)

Picks up one node-element value.

setNodeElements

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

Updates node-element values.

Synchronized so that concurrenct modifications will work correctly.

nodeElements

public List<Dom> nodeElements(String elementName)

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

domNodeByTypeElements

public List<Dom> domNodeByTypeElements(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> List<T> nodeByTypeElements(Class<T> baseType)

nodeByTypeElement

public <T> T nodeByTypeElement(Class<T> baseType)

inject

public void inject(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(String typeName)

Locates the DOM that serves as the symbol space root.

Returns:

always non-null.

resolveReference

public Dom resolveReference(String key,
 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(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> 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

isReified

public boolean isReified()

This ensures no-one tried to reify this descriptor, which has an impl class the interface

Specified by:

isReified in interface org.glassfish.hk2.api.ActiveDescriptor

Overrides:

isReified in class org.glassfish.hk2.utilities.AbstractActiveDescriptor

Returns:

always true

getImplementationClass

public Class<?> getImplementationClass()

Specified by:

getImplementationClass in interface org.glassfish.hk2.api.ActiveDescriptor

getImplementationType

public Type getImplementationType()

Specified by:

getImplementationType in interface org.glassfish.hk2.api.ActiveDescriptor

setImplementationType

public void setImplementationType(Type t)

Overrides:

setImplementationType in class org.glassfish.hk2.utilities.AbstractActiveDescriptor

getContractTypes

public Set<Type> getContractTypes()

Specified by:

getContractTypes in interface org.glassfish.hk2.api.ActiveDescriptor

Overrides:

getContractTypes in class org.glassfish.hk2.utilities.AbstractActiveDescriptor

getScopeAnnotation

public Class<? extends Annotation> getScopeAnnotation()

Specified by:

getScopeAnnotation in interface org.glassfish.hk2.api.ActiveDescriptor

Overrides:

getScopeAnnotation in class org.glassfish.hk2.utilities.AbstractActiveDescriptor

getQualifierAnnotations

public Set<Annotation> getQualifierAnnotations()

Specified by:

getQualifierAnnotations in interface org.glassfish.hk2.api.ActiveDescriptor

Overrides:

getQualifierAnnotations in class org.glassfish.hk2.utilities.AbstractActiveDescriptor

getInjectees

public List<org.glassfish.hk2.api.Injectee> getInjectees()

Specified by:

getInjectees in interface org.glassfish.hk2.api.ActiveDescriptor

Overrides:

getInjectees in class org.glassfish.hk2.utilities.AbstractActiveDescriptor

getFactoryServiceId

public Long getFactoryServiceId()

Specified by:

getFactoryServiceId in interface org.glassfish.hk2.api.ActiveDescriptor

Overrides:

getFactoryServiceId in class org.glassfish.hk2.utilities.AbstractActiveDescriptor

getFactoryLocatorId

public Long getFactoryLocatorId()

Specified by:

getFactoryLocatorId in interface org.glassfish.hk2.api.ActiveDescriptor

Overrides:

getFactoryLocatorId in class org.glassfish.hk2.utilities.AbstractActiveDescriptor

invoke

public Object invoke(Object proxy,
 Method method,
 Object[] args)
              throws 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 InvocationHandler

Throws:

Throwable

invoke

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

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

Throws:

Throwable

getter

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

setter

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

Throws:

Exception

convertName

public static String convertName(String name)

createCreator

protected Creator createCreator(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.

digAnnotation

public static <T extends Annotation> T digAnnotation(Class<?> target,
 Class<T> annotationType)

digAnnotation

public static <T extends Annotation> T digAnnotation(Class<?> target,
 Class<T> annotationType,
 List<Class<? extends Annotation>> visited)

writeTo

public void writeTo(String tagName,
 XMLStreamWriter w)
             throws 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:

XMLStreamException

release

public void release()

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.

getCache

public Object getCache()

Specified by:

getCache in interface org.glassfish.hk2.api.SingleCache

Overrides:

getCache in class org.glassfish.hk2.utilities.AbstractActiveDescriptor

isCacheSet

public boolean isCacheSet()

Specified by:

isCacheSet in interface org.glassfish.hk2.api.SingleCache

Overrides:

isCacheSet in class org.glassfish.hk2.utilities.AbstractActiveDescriptor

setCache

public void setCache(Object cacheMe)

Specified by:

setCache in interface org.glassfish.hk2.api.SingleCache

Overrides:

setCache in class org.glassfish.hk2.utilities.AbstractActiveDescriptor

releaseCache

public void releaseCache()

Specified by:

releaseCache in interface org.glassfish.hk2.api.SingleCache

Overrides:

releaseCache in class org.glassfish.hk2.utilities.AbstractActiveDescriptor

create

public Object create(org.glassfish.hk2.api.ServiceHandle root)

Specified by:

create in interface org.glassfish.hk2.api.ActiveDescriptor

get

public Object get()

getServiceLocator

public org.glassfish.hk2.api.ServiceLocator getServiceLocator()

hashCode

public int hashCode()

Overrides:

hashCode in class org.glassfish.hk2.utilities.AbstractActiveDescriptor

equals

public boolean equals(Object o)

Overrides:

equals in class org.glassfish.hk2.utilities.AbstractActiveDescriptor