Dom (HK2 configuration module 2.1.92 API)

java.lang.Object
- org.glassfish.hk2.utilities.DescriptorImpl
- - org.glassfish.hk2.utilities.AbstractActiveDescriptor
  - - org.jvnet.hk2.config.Dom

All Implemented Interfaces:

java.io.Externalizable, java.io.Serializable, java.lang.reflect.InvocationHandler, ActiveDescriptor, Descriptor, SingleCache, ObservableBean

Direct Known Subclasses:

ConfigBean
```
public class Dom
extends AbstractActiveDescriptor
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 ActiveDescriptor that gets registered into ServiceLocator, so one can access this object by ServiceLocator#getServiceHandle(Class, String) family of methods.

Author:

Kohsuke Kawaguchi

See Also:
Serialized Form

Field Summary

Fields
Modifier and Type Field and Description

DomDocument document
Owner of the DOM tree.

ConfigModel model
Model drives the interpretation of this DOM.

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

Constructor Summary

Constructors
Constructor and Description
`Dom(Dom source, Dom parent)` Copy constructor, used to get a deep copy of the passed instance
`Dom(ServiceLocator habitat, DomDocument document, Dom parent, ConfigModel model)`
`Dom(ServiceLocator habitat, DomDocument document, Dom parent, ConfigModel model, javax.xml.stream.XMLStreamReader in)`

Method Summary

Methods
Modifier and Type	Method and Description
`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.
`java.lang.Object`	`create(ServiceHandle root)`
`protected 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
`boolean`	`equals(java.lang.Object o)`
`java.lang.Object`	`get()`
`java.util.Set<java.lang.String>`	`getAttributeNames()` Returns the list of attributes with a value on this config instance.
`java.lang.Object`	`getCache()`
`java.util.Set<java.lang.reflect.Type>`	`getContractTypes()`
`java.util.Set<java.lang.String>`	`getElementNames()` Returns the children name associated with this config instance.
`java.lang.Long`	`getFactoryLocatorId()`
`java.lang.Long`	`getFactoryServiceId()`
`ServiceLocator`	`getHabitat()`
`java.lang.Class<?>`	`getImplementationClass()`
`java.util.List<Injectee>`	`getInjectees()`
`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
`java.util.Set<java.lang.annotation.Annotation>`	`getQualifierAnnotations()`
`java.lang.Class<? extends java.lang.annotation.Annotation>`	`getScopeAnnotation()`
`ServiceLocator`	`getServiceLocator()`
`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)`
`int`	`hashCode()`
`void`	`initializationCompleted()`
`void`	`inject(java.lang.Object target)` Performs injection to the given object.
`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.
`boolean`	`isCacheSet()`
`boolean`	`isReified()` This ensures no-one tried to reify this descriptor, which has an impl class the interface
`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`	`releaseCache()`
`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`	`setCache(java.lang.Object cacheMe)`
`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)`
`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(java.lang.String tagName, javax.xml.stream.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, removeContractType, removeQualifierAnnotation, setFactoryId, setName, setReified

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, setRanking

- 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(ServiceLocator 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(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 Detail
  - 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 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 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
  - 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 ActiveDescriptor
    
    Overrides:
    
    isReified in class AbstractActiveDescriptor
    
    Returns:
    always true
  - getImplementationClass
```
public java.lang.Class<?> getImplementationClass()
```
    Specified by:
    
    getImplementationClass in interface ActiveDescriptor
  - getContractTypes
```
public java.util.Set<java.lang.reflect.Type> getContractTypes()
```
    Specified by:
    
    getContractTypes in interface ActiveDescriptor
    
    Overrides:
    
    getContractTypes in class AbstractActiveDescriptor
  - getScopeAnnotation
```
public java.lang.Class<? extends java.lang.annotation.Annotation> getScopeAnnotation()
```
    Specified by:
    
    getScopeAnnotation in interface ActiveDescriptor
    
    Overrides:
    
    getScopeAnnotation in class AbstractActiveDescriptor
  - getQualifierAnnotations
```
public java.util.Set<java.lang.annotation.Annotation> getQualifierAnnotations()
```
    Specified by:
    
    getQualifierAnnotations in interface ActiveDescriptor
    
    Overrides:
    
    getQualifierAnnotations in class AbstractActiveDescriptor
  - getInjectees
```
public java.util.List<Injectee> getInjectees()
```
    Specified by:
    
    getInjectees in interface ActiveDescriptor
    
    Overrides:
    
    getInjectees in class AbstractActiveDescriptor
  - getFactoryServiceId
```
public java.lang.Long getFactoryServiceId()
```
    Specified by:
    
    getFactoryServiceId in interface ActiveDescriptor
    
    Overrides:
    
    getFactoryServiceId in class AbstractActiveDescriptor
  - getFactoryLocatorId
```
public java.lang.Long getFactoryLocatorId()
```
    Specified by:
    
    getFactoryLocatorId in interface ActiveDescriptor
    
    Overrides:
    
    getFactoryLocatorId in class AbstractActiveDescriptor
  - 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
  - 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 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.
  - 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
  - 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 java.lang.Object getCache()
```
    Specified by:
    
    getCache in interface SingleCache
    
    Overrides:
    
    getCache in class AbstractActiveDescriptor
  - isCacheSet
```
public boolean isCacheSet()
```
    Specified by:
    
    isCacheSet in interface SingleCache
    
    Overrides:
    
    isCacheSet in class AbstractActiveDescriptor
  - setCache
```
public void setCache(java.lang.Object cacheMe)
```
    Specified by:
    
    setCache in interface SingleCache
    
    Overrides:
    
    setCache in class AbstractActiveDescriptor
  - releaseCache
```
public void releaseCache()
```
    Specified by:
    
    releaseCache in interface SingleCache
    
    Overrides:
    
    releaseCache in class AbstractActiveDescriptor
  - create
```
public java.lang.Object create(ServiceHandle root)
```
    Specified by:
    
    create in interface ActiveDescriptor
  - get
```
public java.lang.Object get()
```
  - getServiceLocator
```
public ServiceLocator getServiceLocator()
```
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class DescriptorImpl
  - equals
```
public boolean equals(java.lang.Object o)
```
    Overrides:
    
    equals in class DescriptorImpl

Class Dom

Field Summary

Constructor Summary

Method Summary

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

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

Methods inherited from class java.lang.Object

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

Field Detail

model

document

Constructor Detail

Dom

Dom

Dom

Method Detail

skipFromXml

writeToXml

initializationCompleted

addDefaultChildren

getHabitat

copy

unwrap

getKey

parent

getLocation

getAttributeNames

getElementNames

attribute

rawAttribute

attributes

attribute

element

leafElement

insertAfter

replaceChild

removeChild

addLeafElement

removeLeafElement

changeLeafElement

rawLeafElement

setLeafElements

leafElements

rawLeafElements

nodeElement

setNodeElements

nodeElements

domNodeByTypeElements

nodeByTypeElements

nodeByTypeElement

inject

getInjector

getSymbolSpaceRoot

resolveReference

createProxy

createProxy

getProxyType

isReified

getImplementationClass

getContractTypes

getScopeAnnotation

getQualifierAnnotations

getInjectees

getFactoryServiceId

getFactoryLocatorId

invoke

invoke

getter

setter

convertName

createCreator

digAnnotation

digAnnotation

writeTo

addListener

removeListener

getCache

isCacheSet

setCache

releaseCache