UnknownElement (Apache Ant API)
Date: 2018-09-12

Package org.apache.tools.ant

## Class UnknownElement

- java.lang.Object
- - org.apache.tools.ant.ProjectComponent
  - - org.apache.tools.ant.Task
    - - org.apache.tools.ant.UnknownElement

- All Implemented Interfaces:
    `java.lang.Cloneable`

      public class UnknownElement
      extends Task

  Wrapper class that holds all the information necessary to create a task or data type that did not exist when Ant started, or one which has had its definition updated to use a different implementation class.

- - ### Field Summary

    - ### Fields inherited from class org.apache.tools.ant.ProjectComponent

      `description, location, project`

    - ### Fields inherited from class org.apache.tools.ant.Task

      `target, taskName, taskType, wrapper`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `UnknownElement​(java.lang.String elementName)` | Creates an UnknownElement for the given element name.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `addChild​(UnknownElement child)` | Adds a child element to this element.
    `void` | `applyPreSet​(UnknownElement u)` | This is used then the realobject of the UE is a PreSetDefinition.
    `void` | `configure​(java.lang.Object realObject)` | Configure the given object from this UnknownElement
    `UnknownElement` | `copy​(Project newProject)` | Make a copy of the unknown element and set it in the new project.
    `void` | `execute()` | Executes the real object if it's a task.
    `java.util.List<UnknownElement>` | `getChildren()` |
    `protected java.lang.String` | `getComponentName()` |
    `java.lang.String` | `getNamespace()` | Return the namespace of the XML element associated with this component.
    `protected BuildException` | `getNotFoundException​(java.lang.String what, java.lang.String name)` | Returns a very verbose exception for when a task/data type cannot be found.
    `java.lang.String` | `getQName()` | Return the qname of the XML element associated with this component.
    `java.lang.Object` | `getRealThing()` | Return the configured object
    `java.lang.String` | `getTag()` | Returns the name of the XML element which generated this unknown element.
    `Task` | `getTask()` | Returns the task instance after it has been created and if it is a task.
    `java.lang.String` | `getTaskName()` | Returns the name to use in logging messages.
    `RuntimeConfigurable` | `getWrapper()` | Get the RuntimeConfigurable instance for this UnknownElement, containing the configuration information.
    `protected void` | `handleChildren​(java.lang.Object parent, RuntimeConfigurable parentWrapper)` | Creates child elements, creates children of the children (recursively), and sets attributes of the child elements.
    `protected void` | `handleErrorFlush​(java.lang.String output)` | Handles error output sent to System.err by this task or its real task.
    `protected void` | `handleErrorOutput​(java.lang.String output)` | Handles error output sent to System.err by this task or its real task.
    `protected void` | `handleFlush​(java.lang.String output)` | Handles output sent to System.out by this task or its real task.
    `protected int` | `handleInput​(byte[] buffer, int offset, int length)` | Delegate to realThing if present and if it as task.
    `protected void` | `handleOutput​(java.lang.String output)` | Handles output sent to System.out by this task or its real task.
    `protected java.lang.Object` | `makeObject​(UnknownElement ue, RuntimeConfigurable w)` | Creates a named task or data type.
    `protected Task` | `makeTask​(UnknownElement ue, RuntimeConfigurable w)` | Creates a named task and configures it up to the init() stage.
    `void` | `maybeConfigure()` | Creates the real object instance and child elements, then configures the attributes and text of the real object.
    `void` | `setNamespace​(java.lang.String namespace)` | Set the namespace of the XML element associated with this component.
    `void` | `setQName​(java.lang.String qname)` | Set the namespace qname of the XML element.
    `void` | `setRealThing​(java.lang.Object realThing)` | Set the configured object
    `boolean` | `similar​(java.lang.Object obj)` | like contents equals, but ignores project

    - ### Methods inherited from class java.lang.Object

      `equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from class org.apache.tools.ant.ProjectComponent

      `clone, getDescription, getLocation, getProject, setDescription, setLocation, setProject`

    - ### Methods inherited from class org.apache.tools.ant.Task

      `bindToOwner, getOwningTarget, getRuntimeConfigurableWrapper, getTaskType, init, isInvalid, log, log, log, log, perform, reconfigure, setOwningTarget, setRuntimeConfigurableWrapper, setTaskName, setTaskType`

- - ### Constructor Detail

    - #### UnknownElement

          public UnknownElement​(java.lang.String elementName)

      Creates an UnknownElement for the given element name.
      Parameters:
        `elementName` - The name of the unknown element. Must not be `null`.

  - ### Method Detail

    - #### getChildren

          public java.util.List<UnknownElement> getChildren()

      Returns:
        the list of nested UnknownElements for this UnknownElement.

    - #### getTag

          public java.lang.String getTag()

      Returns the name of the XML element which generated this unknown element.
      Returns:
        the name of the XML element which generated this unknown element.

    - #### getNamespace

          public java.lang.String getNamespace()

      Return the namespace of the XML element associated with this component.
      Returns:
        Namespace URI used in the xmlns declaration.

    - #### setNamespace

          public void setNamespace​(java.lang.String namespace)

      Set the namespace of the XML element associated with this component. This method is typically called by the XML processor. If the namespace is "ant:current", the component helper is used to get the current antlib uri.
      Parameters:
        `namespace` - URI used in the xmlns declaration.

    - #### getQName

          public java.lang.String getQName()

      Return the qname of the XML element associated with this component.
      Returns:
        namespace Qname used in the element declaration.

    - #### setQName

          public void setQName​(java.lang.String qname)

      Set the namespace qname of the XML element. This method is typically called by the XML processor.
      Parameters:
        `qname` - the qualified name of the element

    - #### getWrapper

          public RuntimeConfigurable getWrapper()

      Get the RuntimeConfigurable instance for this UnknownElement, containing the configuration information.
      Overrides:
        `getWrapper` in class `Task`
      Returns:
        the configuration info.

    - #### maybeConfigure

          public void maybeConfigure()
                              throws BuildException

      Creates the real object instance and child elements, then configures the attributes and text of the real object. This unknown element is then replaced with the real object in the containing target's list of children.
      Overrides:
        `maybeConfigure` in class `Task`
      Throws:
        `BuildException` - if the configuration fails

    - #### configure

          public void configure​(java.lang.Object realObject)

      Configure the given object from this UnknownElement
      Parameters:
        `realObject` - the real object this UnknownElement is representing.

    - #### handleOutput

          protected void handleOutput​(java.lang.String output)

      Handles output sent to System.out by this task or its real task.
      Overrides:
        `handleOutput` in class `Task`
      Parameters:
        `output` - The output to log. Should not be `null`.

    - #### handleInput

          protected int handleInput​(byte[] buffer,
                                    int offset,
                                    int length)
                             throws java.io.IOException

      Delegate to realThing if present and if it as task.
      Overrides:
        `handleInput` in class `Task`
      Parameters:
        `buffer` - the buffer into which data is to be read.
        `offset` - the offset into the buffer at which data is stored.
        `length` - the amount of data to read.
      Returns:
        the number of bytes read.
      Throws:
        `java.io.IOException` - if the data cannot be read.
      Since:
        Ant 1.6
      See Also:
        `Task.handleInput(byte[], int, int)`

    - #### handleFlush

          protected void handleFlush​(java.lang.String output)

      Handles output sent to System.out by this task or its real task.
      Overrides:
        `handleFlush` in class `Task`
      Parameters:
        `output` - The output to log. Should not be `null`.

    - #### handleErrorOutput

          protected void handleErrorOutput​(java.lang.String output)

      Handles error output sent to System.err by this task or its real task.
      Overrides:
        `handleErrorOutput` in class `Task`
      Parameters:
        `output` - The error output to log. Should not be `null`.

    - #### handleErrorFlush

          protected void handleErrorFlush​(java.lang.String output)

      Handles error output sent to System.err by this task or its real task.
      Overrides:
        `handleErrorFlush` in class `Task`
      Parameters:
        `output` - The error output to log. Should not be `null`.

    - #### execute

          public void execute()

      Executes the real object if it's a task. If it's not a task (e.g. a data type) then this method does nothing.
      Overrides:
        `execute` in class `Task`

    - #### addChild

          public void addChild​(UnknownElement child)

      Adds a child element to this element.
      Parameters:
        `child` - The child element to add. Must not be `null`.

    - #### handleChildren

          protected void handleChildren​(java.lang.Object parent,
                                        RuntimeConfigurable parentWrapper)
                                 throws BuildException

      Creates child elements, creates children of the children (recursively), and sets attributes of the child elements.
      Parameters:
        `parent` - The configured object for the parent. Must not be `null`.
        `parentWrapper` - The wrapper containing child wrappers to be configured. Must not be `null` if there are any children.
      Throws:
        `BuildException` - if the children cannot be configured.

    - #### getComponentName

          protected java.lang.String getComponentName()

      Returns:
        the component name - uses ProjectHelper#genComponentName()

    - #### applyPreSet

          public void applyPreSet​(UnknownElement u)

      This is used then the realobject of the UE is a PreSetDefinition. This is also used when a presetdef is used on a presetdef The attributes, elements and text are applied to this UE.
      Parameters:
        `u` - an UnknownElement containing the attributes, elements and text

    - #### makeObject

          protected java.lang.Object makeObject​(UnknownElement ue,
                                                RuntimeConfigurable w)

      Creates a named task or data type. If the real object is a task, it is configured up to the init() stage.
      Parameters:
        `ue` - The unknown element to create the real object for. Must not be `null`.
        `w` - Ignored in this implementation.
      Returns:
        the task or data type represented by the given unknown element.

    - #### makeTask

          protected Task makeTask​(UnknownElement ue,
                                  RuntimeConfigurable w)

      Creates a named task and configures it up to the init() stage.
      Parameters:
        `ue` - The UnknownElement to create the real task for. Must not be `null`.
        `w` - Ignored.
      Returns:
        the task specified by the given unknown element, or `null` if the task name is not recognised.

    - #### getNotFoundException

          protected BuildException getNotFoundException​(java.lang.String what,
                                                        java.lang.String name)

      Returns a very verbose exception for when a task/data type cannot be found.
      Parameters:
        `what` - The kind of thing being created. For example, when a task name could not be found, this would be `"task"`. Should not be `null`.
        `name` - The name of the element which could not be found. Should not be `null`.
      Returns:
        a detailed description of what might have caused the problem.

    - #### getTaskName

          public java.lang.String getTaskName()

      Returns the name to use in logging messages.
      Overrides:
        `getTaskName` in class `Task`
      Returns:
        the name to use in logging messages.

    - #### getTask

          public Task getTask()

      Returns the task instance after it has been created and if it is a task.
      Returns:
        a task instance or `null` if the real object is not a task.

    - #### getRealThing

          public java.lang.Object getRealThing()

      Return the configured object
      Returns:
        the real thing whatever it is
      Since:
        ant 1.6

    - #### setRealThing

          public void setRealThing​(java.lang.Object realThing)

      Set the configured object
      Parameters:
        `realThing` - the configured object
      Since:
        ant 1.7

    - #### similar

          public boolean similar​(java.lang.Object obj)

      like contents equals, but ignores project
      Parameters:
        `obj` - the object to check against
      Returns:
        true if this UnknownElement has the same contents the other

    - #### copy

          public UnknownElement copy​(Project newProject)

      Make a copy of the unknown element and set it in the new project.
      Parameters:
        `newProject` - the project to create the UE in.
      Returns:
        the copied UE.