# XNodeRef.java

    /*
    ** Module   : XNodeRef
    ** Abstract : DOM XML Node reference resource type interface.
    **
    ** Copyright (c) 2013-2017, Golden Code Development Corporation.
    **
    ** -#- -I- --Date-- ---------------------------------Description---------------------------------
    ** 001 EVL 20130130 Created initial version.
    ** 002 CA  20130221 Added LOCAL-NAME support.
    ** 003 EVL 20130222 Adding NODE-VALUE attribute and SET-ATTRIBUTE-NODE method.
    ** 004 EVK 20130531 Adding NODE-VALUE attribute and GET-PARENT, GET-ATTRIBUTE-NODE, NORMALIZE
    **                  LONGCHAR-TO-NODE-VALUE, NODE-VALUE-TO-LONGCHAR, CLONE-NODE methods.
    ** 005 CA  20130927 Added LegacyResource annotation, to determine resource type.
    ** 006 EVL 20131002 Adding legacy attributes and methods annotation.
    ** 007 OM  20170829 Added _POLY capability to NODE-VALUE setter attribute.
    */

    /*
    ** This program is free software: you can redistribute it and/or modify
    ** it under the terms of the GNU Affero General Public License as
    ** published by the Free Software Foundation, either version 3 of the
    ** License, or (at your option) any later version.
    **
    ** This program is distributed in the hope that it will be useful,
    ** but WITHOUT ANY WARRANTY; without even the implied warranty of
    ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    ** GNU Affero General Public License for more details.
    **
    ** You may find a copy of the GNU Affero GPL version 3 at the following
    ** location: https://www.gnu.org/licenses/agpl-3.0.en.html
    **
    ** Additional terms under GNU Affero GPL version 3 section 7:
    **
    **   Under Section 7 of the GNU Affero GPL version 3, the following additional
    **   terms apply to the works covered under the License.  These additional terms
    **   are non-permissive additional terms allowed under Section 7 of the GNU
    **   Affero GPL version 3 and may not be removed by you.
    **
    **   0. Attribution Requirement.
    **
    **     You must preserve all legal notices or author attributions in the covered
    **     work or Appropriate Legal Notices displayed by works containing the covered
    **     work.  You may not remove from the covered work any author or developer
    **     credit already included within the covered work.
    **
    **   1. No License To Use Trademarks.
    **
    **     This license does not grant any license or rights to use the trademarks
    **     Golden Code, FWD, any Golden Code or FWD logo, or any other trademarks
    **     of Golden Code Development Corporation. You are not authorized to use the
    **     name Golden Code, FWD, or the names of any author or contributor, for
    **     publicity purposes without written authorization.
    **
    **   2. No Misrepresentation of Affiliation.
    **
    **     You may not represent yourself as Golden Code Development Corporation or FWD.
    **
    **     You may not represent yourself for publicity purposes as associated with
    **     Golden Code Development Corporation, FWD, or any author or contributor to
    **     the covered work, without written authorization.
    **
    **   3. No Misrepresentation of Source or Origin.
    **
    **     You may not represent the covered work as solely your work.  All modified
    **     versions of the covered work must be marked in a reasonable way to make it
    **     clear that the modified work is not originating from Golden Code Development
    **     Corporation or FWD.  All modified versions must contain the notices of
    **     attribution required in this license.
    */

    package com.goldencode.p2j.xml;

    import com.goldencode.p2j.util.*;

    /**
     * Interface describing X-Node-Reference specific features of the DOM XML
     * objects.
     */
    @LegacyResource(resource = LegacyResource.X_NODEREF)
    public interface XNodeRef
    extends XEntity,
            LocalName
    {
       // Attributes
       /**
        * Getting the attribute names available for current node reference.
        *
        * @return   The comma separated character string of all available
        *           attributed.
        */
       @LegacyAttribute(name = "ATTRIBUTE-NAMES")
       public character getAttributeNames();

       /**
        * Getting the Parent of current node.
        *
        * @param    hNoderefParent
        *           A valid handle to assign parent XML node.
        *
        * @return   The <code>true</code> in case of success
        *           <code>false</code> otherwise.
        */
       @LegacyMethod(name = "GET-PARENT")
       public logical getParent(handle hNoderefParent);

       /**
        * Getting the value of the XML node value attribute.
        *
        * @return   The character value of the node reference.
        */
       @LegacyAttribute(name = "NODE-VALUE")
       public character getNodeValue();

       /**
        * Setting the value of the XML node value attribute.
        *
        * @param    value
        *           The new value of the node value attribute.
        */
       @LegacyAttribute(name = "NODE-VALUE", setter = true)
       public void setNodeValue(character value);

       /**
        * Setting the value of the XML node value attribute.
        *
        * @param    value
        *           The new value of the node value attribute.
        */
       @LegacyAttribute(name = "NODE-VALUE", setter = true)
       public void setNodeValue(String value);

       /**
        * Setting the value of the XML node value attribute. {@code NODE-VALUE} is a _POLY attribute,
        * it accepts any value (any type) and it will silently convert it to {@code CHARACTER}
        * on-the-fly.
        *
        * @param   value
        *          The new value of the node value attribute.
        */
       @LegacyAttribute(name = "NODE-VALUE", setter = true)
       public default void setNodeValue(BaseDataType value)
       {
          if (value instanceof character)
          {
             setNodeValue((character) value);
          }
          else
          {
             setNodeValue(new character(value));
          }
       }

       // Methods
       /**
        * Deleting the internals of the current X-Node-Reference.
        *
        * @return   The <code>true</code> in case of success
        *           <code>false</code> otherwise.
        */
       @LegacyMethod(name = "DELETE-NODE")
       public logical deleteNode();

       /**
        * Getting the attribute value for a given attribute name.
        *
        * @param    name
        *           The name of the attribute to return.
        *
        * @return   The comma separated character string of all available
        *           attributed.
        */
       @LegacyMethod(name = "GET-ATTRIBUTE")
       public character getAttribute(String name);

       /**
        * Getting the attribute value for a given attribute name.
        *
        * @param    name
        *           The name of the attribute to return.
        *
        * @return   The comma separated character string of all available
        *           attributed.
        */
       @LegacyMethod(name = "GET-ATTRIBUTE")
       public character getAttribute(character name);

       /**
        * Setting the attribute value for a given attribute name.
        *
        * @param    name
        *           The name of the attribute to change.
        * @param    value
        *           The new value for the given attribute name.
        *
        * @return   The <code>true</code> in case of success
        *           <code>false</code> otherwise.
        */
       @LegacyMethod(name = "SET-ATTRIBUTE")
       public logical setAttribute(String name, String value);

       /**
        * Setting the attribute value for a given attribute name.
        *
        * @param    name
        *           The name of the attribute to change.
        * @param    value
        *           The new value for the given attribute name.
        *
        * @return   The <code>true</code> in case of success
        *           <code>false</code> otherwise.
        */
       @LegacyMethod(name = "SET-ATTRIBUTE")
       public logical setAttribute(String name, character value);

       /**
        * Setting the attribute value for a given attribute name.
        *
        * @param    name
        *           The name of the attribute to change.
        * @param    value
        *           The new value for the given attribute name.
        *
        * @return   The <code>true</code> in case of success
        *           <code>false</code> otherwise.
        */
       @LegacyMethod(name = "SET-ATTRIBUTE")
       public logical setAttribute(character name, String value);

       /**
        * Setting the attribute value for a given attribute name.
        *
        * @param    name
        *           The name of the attribute to change.
        * @param    value
        *           The new value for the given attribute name.
        *
        * @return   The <code>true</code> in case of success
        *           <code>false</code> otherwise.
        */
       @LegacyMethod(name = "SET-ATTRIBUTE")
       public logical setAttribute(character name, character value);

       /**
        * Associates XML attribute node with the given X-Noderef object handle.
        *
        * @param    handle
        *           The handle that represents an XML attribute node created with create node or
        *           create node namespace.
        *
        * @return   The <code>true</code> in case of success <code>false</code> otherwise.
        */
       @LegacyMethod(name = "SET-ATTRIBUTE-NODE")
       public logical setAttributeNode(handle handle);

       /**
        * Associates XML attribute node with the specified name to the given X-Noderef object
        * handle.
        *
        * @param    handle
        *           The handle that represents an XML attribute node with the specified name.
        * @param    attributeName
        *           The string that represents an XML attribute node with the specified name.
        *
        * @return   The <code>true</code> in case of success <code>false</code> otherwise.
        */
       @LegacyMethod(name = "GET-ATTRIBUTE-NODE")
       public logical getAttributeNode(handle handle, String attributeName);

       /**
        * Associates XML attribute node with the specified name to the given X-Noderef object
        * handle.
        *
        * @param    handle
        *           The handle that represents an XML attribute node with the specified name.
        * @param    attributeName
        *           The character that represents an XML attribute node with the specified name.
        *
        * @return   The <code>true</code> in case of success <code>false</code> otherwise.
        */
       @LegacyMethod(name = "GET-ATTRIBUTE-NODE")
       public logical getAttributeNode(handle handle, character attributeName);

       /**
        * Setting the binary value of the XML node value attribute.
        *
        * @param    value
        *           The new value of the node value attribute.
        *
        * @return   The <code>true</code> in case of success <code>false</code> otherwise.
        */
       @LegacyMethod(name = "LONGCHAR-TO-NODE-VALUE")
       public logical longcharToNodeValue(longchar value);

       /**
        * Setting the XML node value attribute to binary value of longchar.
        *
        * @param    value
        *           To save the value on XML node to this parameter.
        *
        * @return   The <code>true</code> in case of success <code>false</code> otherwise.
        */
       @LegacyMethod(name = "NODE-VALUE-TO-LONGCHAR")
       public logical nodeValueToLongchar(longchar value);

       /**
        * Setting the binary value of the XML node value attribute.
        *
        * @param    value
        *           The new value of the node value attribute.
        *
        * @return   The <code>true</code> in case of success <code>false</code> otherwise.
        */
       @LegacyMethod(name = "MEMPTR-TO-NODE-VALUE")
       public logical memptrToNodeValue(memptr value);

       /**
        * Setting the XML node value attribute to binary value of memptr.
        *
        * @param    value
        *           To save the value on XML node to this parameter.
        *
        * @return   The <code>true</code> in case of success <code>false</code> otherwise.
        */
       @LegacyMethod(name = "NODE-VALUE-TO-MEMPTR")
       public logical nodeValueToMemptr(memptr value);

       /**
        * Creating the new node within the current Document object.
        *
        * @param    xNodeRef
        *           The valid handle class instance to use for the cloned XML node.
        * @param    deep
        *           A logical that if <code>true</code> specifies that the whole sub-trees is to
        *           be copied. The default value is {@code false}.
        *
        * @return   The <code>true</code> in case of success <code>false</code> otherwise.
        */
       @LegacyMethod(name = "CLONE-NODE")
       public logical cloneNode(handle xNodeRef, logical deep);

       /**
        * Creating the new node within the current Document object.
        *
        * @param    xNodeRef
        *           The valid handle class instance to use for the cloned XML node.
        * @param    deep
        *           A logical that if <code>true</code> specifies that the whole sub-trees is to
        *           be copied. The default value is {@code false}.
        *
        * @return   The <code>true</code> in case of success <code>false</code> otherwise.
        */
       @LegacyMethod(name = "CLONE-NODE")
       public logical cloneNode(handle xNodeRef, boolean deep);

       /**
        * Normalizes TEXT and ATTRIBUTE nodes in the full depth of the sub-tree under this
        * XML node.
        *
        * @return   The <code>true</code> in case of success <code>false</code> otherwise.
        */
       @LegacyMethod(name = "NORMALIZE")
       public logical normalize();
    }