org.jvnet.hk2.config
Class Dom

java.lang.Object
  extended by org.glassfish.hk2.utilities.DescriptorImpl
      extended by com.sun.hk2.component.AbstractInhabitantImpl<T>
          extended by com.sun.hk2.component.EventPublishingInhabitant<T>
              extended by com.sun.hk2.component.LazyInhabitant
                  extended by org.jvnet.hk2.config.Dom
All Implemented Interfaces:
ClassLoaderHolder, Holder, Serializable, InvocationHandler, ActiveDescriptor, Descriptor, SingleCache, Binding, Factory, ManagedComponentProvider, Provider, Releasable, Inhabitant, ObservableBean
Direct Known Subclasses:
ConfigBean

public class Dom
extends LazyInhabitant
implements ActiveDescriptor, 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
See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from interface com.sun.hk2.component.Holder
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.EventPublishingInhabitant
real
 
Fields inherited from class com.sun.hk2.component.AbstractInhabitantImpl
descriptor, logger
 
Constructor Summary
Dom(Dom source, Dom parent)
          Copy constructor, used to get a deep copy of the passed instance
Dom(Habitat habitat, DomDocument document, Dom parent, ConfigModel model)
           
Dom(Habitat habitat, DomDocument document, Dom parent, ConfigModel model, XMLStreamReader in)
           
 
Method Summary
 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(ServiceHandle root)
          Creates an instance of the ActiveDescriptor.
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
 Object get(Inhabitant onBehalfOf)
          Returns the instance of this inhabitant.
 Set<String> getAttributeNames()
          Returns the list of attributes with a value on this config instance.
 BaseServiceLocator getBaseServiceLocator()
           
 Object getCache()
          This can be used for scopes that will only every be created once.
 Set<Type> getContractTypes()
          The set of types that this ActiveDescriptor must produce.
 Set<String> getElementNames()
          Returns the children name associated with this config instance.
 Long getFactoryLocatorId()
          If this ActiveDescriptor has DescriptorType of PROVIDE_METHOD then this field will return the ServiceId of its associated Factory service.
 Long getFactoryServiceId()
          If this ActiveDescriptor has DescriptorType of PROVIDE_METHOD then this field will return the ServiceId of its associated Factory service.
 Habitat getHabitat()
           
 Class<?> getImplementationClass()
          The implementation class that should be used to generate new instances of this descriptor.
 List<Injectee> getInjectees()
          Returns the full list of Injectees this class has.
 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()
          The full set of qualifiers that this ActiveDescriptor provides
 Class<? extends Annotation> getScopeAnnotation()
          Returns the scope that this ActiveDescriptor belongs to
 Dom getSymbolSpaceRoot(String typeName)
          Locates the DOM that serves as the symbol space root.
protected  Object getter(ConfigModel.Property target, Type t)
           
 void initializationCompleted()
           
 void inject(Object target)
          Performs injection to the given object.
protected  void injectInto(Dom injectable, Object target)
           
 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()
          Returns true if this cache has been set
 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()
          Called to orderly shutdown ServiceLocator.
 void releaseCache()
          Removes the cached value and makes it such that this cache has not been set
 void removeChild(Dom reference)
          Removes an existing 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 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)
          Sets the value into the cache
 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)
           
static Dom unwrap(ConfigBeanProxy proxy)
          Unwraps the proxy and returns the underlying Dom object.
 void writeTo(String tagName, XMLStreamWriter w)
          Writes back this element.
 
Methods inherited from class com.sun.hk2.component.LazyInhabitant
fetch, getClassLoader, lead, loadClass, metadata, type, type, typeName
 
Methods inherited from class com.sun.hk2.component.EventPublishingInhabitant
addInhabitantListener, equals, getServiceLocator, hashCode, isActive, notify, removeInhabitantListener, toString
 
Methods inherited from class com.sun.hk2.component.AbstractInhabitantImpl
companions, dispose, get, getAnnotation, getAnnotation, getAnnotations, getByType, getDescriptor, getDescriptorFor, getProvider, getProvider, getSerializedMetadata, getSerializedMetadata, matches, setCompanions
 
Methods inherited from class org.glassfish.hk2.utilities.DescriptorImpl
addAdvertisedContract, addMetadata, addQualifier, getAdvertisedContracts, getBaseDescriptor, getDescriptorType, getImplementation, getLoader, getLocatorId, getMetadata, getName, getQualifiers, getRanking, getScope, getServiceId, pretty, readObject, removeAdvertisedContract, removeAllMetadata, removeMetadata, removeQualifier, setBaseDescriptor, setDescriptorType, setImplementation, setLoader, setLocatorId, setName, setRanking, setScope, setServiceId, writeObject
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 
Methods inherited from interface org.glassfish.hk2.api.ActiveDescriptor
dispose
 
Methods inherited from interface org.glassfish.hk2.api.Descriptor
getAdvertisedContracts, getBaseDescriptor, getDescriptorType, getImplementation, getLoader, getLocatorId, getMetadata, getName, getQualifiers, getRanking, getScope, getServiceId, 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(Habitat 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(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.


getHabitat

public Habitat 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 ConfigModel.getAttributeNames.

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 NodeChild with another one.

See Also:
insertAfter(Dom, String, Dom)

removeChild

public void removeChild(Dom reference)
Removes an existing 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 ActiveDescriptor
Returns:
always true

getImplementationClass

public Class<?> getImplementationClass()
Description copied from interface: ActiveDescriptor
The implementation class that should be used to generate new instances of this descriptor.

If the class returned is a Factory, then the factory is used to create instances. In this case the system will get an instance of the factory and use it to create the instances

Specified by:
getImplementationClass in interface ActiveDescriptor
Returns:
The class that directly implements the contract types, or the class that is the factory for an object that implements the contract types

getContractTypes

public Set<Type> getContractTypes()
Description copied from interface: ActiveDescriptor
The set of types that this ActiveDescriptor must produce. These types may be Classes or ParameterizedTypes, and may be no other subclass of Type

Specified by:
getContractTypes in interface ActiveDescriptor
Returns:
the set of types this ActiveDescriptor must implement or extend

getScopeAnnotation

public Class<? extends Annotation> getScopeAnnotation()
Description copied from interface: ActiveDescriptor
Returns the scope that this ActiveDescriptor belongs to

Specified by:
getScopeAnnotation in interface ActiveDescriptor
Returns:
The scope of this ActiveDescriptor

getQualifierAnnotations

public Set<Annotation> getQualifierAnnotations()
Description copied from interface: ActiveDescriptor
The full set of qualifiers that this ActiveDescriptor provides

Specified by:
getQualifierAnnotations in interface ActiveDescriptor
Returns:
The set of annotations that this ActiveDescriptor provides

getInjectees

public List<Injectee> getInjectees()
Description copied from interface: ActiveDescriptor
Returns the full list of Injectees this class has. These references will be resolved prior to the class being constructed, even if these injectees are field or method injectees.

If this descriptor is describing a factory created type then this list must have zero length

Specified by:
getInjectees in interface ActiveDescriptor
Returns:
Will not return null, but may return an empty list. The set of Injectees that must be resolved before this ActiveDescriptor can be constructed

getFactoryServiceId

public Long getFactoryServiceId()
Description copied from interface: ActiveDescriptor
If this ActiveDescriptor has DescriptorType of PROVIDE_METHOD then this field will return the ServiceId of its associated Factory service. Otherwise this method should return null

Specified by:
getFactoryServiceId in interface ActiveDescriptor
Returns:
The service ID of the associated factory service

getFactoryLocatorId

public Long getFactoryLocatorId()
Description copied from interface: ActiveDescriptor
If this ActiveDescriptor has DescriptorType of PROVIDE_METHOD then this field will return the ServiceId of its associated Factory service. Otherwise this method should return null

Specified by:
getFactoryLocatorId in interface ActiveDescriptor
Returns:
The locator ID of the associated factory service

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

getBaseServiceLocator

public BaseServiceLocator getBaseServiceLocator()

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.

Overrides:
createCreator in class LazyInhabitant

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

injectInto

protected void injectInto(Dom injectable,
                          Object target)

release

public void release()
Description copied from interface: Inhabitant
Called to orderly shutdown ServiceLocator.

The expected behavior is for objects to get its PreDestroy callback invoked, and its reference released. For singleton objects, this method is expected to dispose that object.

For scoped objects, those are released when ScopeInstance.release() is invoked.

Specified by:
release in interface Releasable
Specified by:
release in interface Inhabitant
Overrides:
release in class 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.

getCache

public Object getCache()
Description copied from interface: SingleCache
This can be used for scopes that will only every be created once. The returned value must have been set previously with setCache. If this is called when isCacheSet is false will result in a RuntimeException

Specified by:
getCache in interface SingleCache
Returns:
A value cached with this ActiveDescriptor

isCacheSet

public boolean isCacheSet()
Description copied from interface: SingleCache
Returns true if this cache has been set

Specified by:
isCacheSet in interface SingleCache
Returns:
true if there is a currently cached value, false otherwise

setCache

public void setCache(Object cacheMe)
Description copied from interface: SingleCache
Sets the value into the cache

Specified by:
setCache in interface SingleCache
Parameters:
cacheMe - A single value that can be cached in this active descriptor

releaseCache

public void releaseCache()
Description copied from interface: SingleCache
Removes the cached value and makes it such that this cache has not been set

Specified by:
releaseCache in interface SingleCache

create

public Object create(ServiceHandle root)
Description copied from interface: ActiveDescriptor
Creates an instance of the ActiveDescriptor. All of the Injectee's must be created prior to instantiation, and associated with the ExtendedProvider so that they can be destroyed properly

Specified by:
create in interface ActiveDescriptor
Parameters:
root - The root service handle, which can be used to associated all the PerLookup objects with this creation
Returns:
An instance of this ActiveDescriptor

get

public Object get(Inhabitant onBehalfOf)
Description copied from interface: Inhabitant
Returns the instance of this inhabitant.

THIS METHOD SHOULD BE ONLY USED BY HK2 IMPLEMENTATION.

Inhabitants are often used with the decorator pattern (see AbstractCreatorInhabitantImpl for example), yet during the object initializtion inside the Inhabitant.get() method, we often need the reference to the outer-most Inhabitant registered to the ServiceLocator (for example so that we can request the injection of {link Inhabita} that represents itself, or to inject companions.)

So this overloaded version of the get method takes the outer-most Inhabitant. This method is only invoked from within HK2 where the decorator pattern is used.

Specified by:
get in interface Inhabitant
Overrides:
get in class EventPublishingInhabitant


Copyright © 2013 Oracle Corporation. All Rights Reserved.