Package org.glassfish.hk2.xml.api

Interface XmlRootHandle<T>

All Known Implementing Classes:
XmlRootHandleImpl
public interface XmlRootHandle<T>
This represents XML data and a JavaBean tree
Author:
jwells

  • Method Details

    • getRoot

      T getRoot()
      Gets the root of the JavaBean tree
      Returns:
      The root of the JavaBean tree. Will only return null if the tree has not yet been created

    • getRootClass

      Class<T> getRootClass()
      Returns the root interface of this handle
      Returns:
      The root class or interface of this handle. Will not return null

    • getURI

      URI getURI()
      Represents the original URI from which this tree was parsed (or null if this tree did not come from a URI)
      Returns:
      The original URI from which this tree was parsed, or null if this tree did not come from a URI

    • isAdvertisedInLocator

      boolean isAdvertisedInLocator()
      Returns true if this handles root and children are advertised in it service locator
      Returns:
      true if the root and children are advertised in the associated service locator

    • isAdvertisedInHub

      boolean isAdvertisedInHub()
      Returns true if this handles root and children are advertised in the Hub
      Returns:
      true if the root and children are advertised in the associated Hub

    • getReadOnlyRoot

      T getReadOnlyRoot(boolean representDefaults)
      This method returns a read-only copy of the existing tree. Any method that would change anything in this tree will fail. Methods that are customized will also fail

      If representsDefaults is true then getters for unset fields will return the default value. If representsDefaults is false then getters for unset fields will return null (or 0 (and false) for scalars). Setting representsDefault to false is useful if this tree is to be used to marshall back to XML, since JAXB will then not write the values back out to the file

      Parameters:
      representDefaults - If true getters will return default values, if false getters will return null (or zero/false for scalars)
      Returns:
      A read-only copy of this xml tree or null if there is no current root for this handle

    • getXmlRootCopy

      XmlRootCopy<T> getXmlRootCopy()
      Creates a copy of this tree that is not advertised. Modifications can be made to this copy and then merged back into the parent in a single transaction

      There is no requirement to call XmlRootCopy.merge() since the parent keeps no track of children. However, the XmlRootCopy.merge() method will fail if a modification has been made to the parent since the time the copy was created

      Returns:
      A non-null copy of this root that can be modified and then merged back in a single transaction

    • overlay

      void overlay(XmlRootHandle<T> newRoot)
      This method overlays the current root and children with the root and children from newRoot. newRoot must have the same rootClass and must NOT be advertised in either the locator or the hub. The system will calculate the set of changes needed to convert this root into the root from newRoot.

      All nodes that are at the same spot in the tree (have the same xpath and same instance name) will not be modified, but will instead have attributes changed. All nodes present in newRoot but not in this root will be considered adds. All nodes not present in newRoot but in this root will be considered deletes

      The URI will not be modified by this call, nor will the state of advertisement

      Parameters:
      newRoot - The non-null root that will be overlayed onto this handle

    • addRoot

      void addRoot(T root)
      If this handle does not already have a root bean this method will add the one given
      Parameters:
      root - The non-null instance of the root type of this handle
      Throws:
      IllegalStateException - if this handle already has a root

    • addRoot

      void addRoot()
      This method can be used if the root of the tree has no required fields, and is the combination of XmlService.createBean(Class) and addRoot(Object). This method will throw an exception from the validator (if validation is enabled) if the root type has required fields or fails other validation

    • removeRoot

      T removeRoot()
      If this handle has a root this method will delete it and all children, leaving the root of this tree null
      Returns:
      The root that was deleted, or null if the root was already null

    • addChangeListener

      void addChangeListener(VetoableChangeListener... listeners)
      Adds a change listener to be invoked before any property is set or a bean is added. The listener must be suitable for storage in a HashSet.

      Rules for change listener:

      • Adds of beans with children will get called back for each child and sub-child added
      • Add listener callbacks will happen parent first but children at the same level are handled in any order
      • When adding a bean the following events will be generated:
        1. An event with an empty string as the propertyName, oldValue null, newValue and source set to the added bean
        2. An event for the parent being added to with propertyName, oldValue the old list or array or direct child, new value the new list or array or direct child
      • Remove listener callbacks will happen child first but children at the same level are handled in any order
      • When removing a bean the following events will be generated:
        1. An event with an empty string as the propertyName, oldValue the removed bean, newValue null, and source set to the removed bean
        2. An event for the parent being removed from with propertyName, oldValue the old list or array or direct child, new value the new list or array or null for the direct child
      • Listeners are run in the order in which they are added
      • If a listener throws a PropertyVetoException subsequent listeners are NOT called and the update will not happen
      • If a listener throws any exception other than PropertyVertoException subsequent listeners WILL be called and the update will not happen
      • If any exceptions happen in any listeners they will end up all being reported in a MultiException
      Parameters:
      listeners - non-null listeners to be called whenever a property is changed in any bean in this root. Must be suitable for storage in a HashSet

    • removeChangeListener

      void removeChangeListener(VetoableChangeListener... listeners)
      Removes a change listener. The listener must be suitable for lookup in a HashSet
      Parameters:
      listener - non-null listeners to be removed. Must be suitable for lookup in a HashSet

    • getChangeListeners

      List<VetoableChangeListener> getChangeListeners()
      Gets the current list of change listeners
      Returns:
      The non-null but possibly empty list of change listeners to be called when a bean is added, removed or modified

    • lockForTransaction

      XmlHandleTransaction<T> lockForTransaction() throws IllegalStateException
      This method will lock the bean tree represented by this XmlRootHandle and start a transaction. Any changes made while this transaction is in-flight will not be visible to any other thread until this transaction is committed. This transaction MUST be committed or abandoned before any other thread can get access to any beans in this tree.

      In particular, the code using this transaction should logically behave like the following code: 

       XmlHandleTransaction transaction = root.lockForTransaction();
 try {
   // Do many many edits all at once
 }
 finally {
   transaction.commit();
 }
      Returns:
      The never null transaction object that must either be abandoned or committed before the write lock on this bean tree is released
      Throws:
      IllegalStateException - if this bean tree is not allowed to have a transaction started on it

    • startValidating

      void startValidating()
      Does javax validation on the root bean from the root. This will cause every change hereafter to be validated
      Throws:
      ConstraintViolationException

    • stopValidating

      void stopValidating()
      Stops this root handle from doing javax validation on modifications

    • isValidating

      boolean isValidating()
      True if this handle is currently validating changes

    • marshal

      void marshal(OutputStream outputStream) throws IOException
      Will marshal this tree into the given stream. Will hold the read lock of this tree while it does so that the tree cannot change underneath while it is being written out. It will use a basic indentation and new-line scheme
      Parameters:
      outputStream - A non-closed output stream. This method will not close the output stream
      Throws:
      IOException - On any exception that might happen

    • marshal

      void marshal(OutputStream outputStream, Map<String,Object> options) throws IOException
      Will marshal this tree into the given stream. Will hold the read lock of this tree while it does so that the tree cannot change underneath while it is being written out. It will use a basic indentation and new-line scheme
      Parameters:
      outputStream - A non-closed output stream. This method will not close the output stream
      options - optional (possibly null) options from the caller
      Throws:
      IOException - On any exception that might happen