# NoopDescriptor.java

    /*
    ** Module   : NoopDescriptor.java
    ** Abstract : Test descriptor which does nothing.
    **
    ** Copyright (c) 2023-2024, Golden Code Development Corporation.
    **
    ** -#- -I- --Date-- ---------------------------------Description---------------------------------
    ** 001 VVT 20230318 Created initial version.
    ** 002 VVT 20240321 Access to the parent test descriptor field changed to protected. See #8406.
    ** 003 VVT 20240614 The class now implements Node<FWDEngineExecutionContext>, and the execute()
    **                  method always throws an exception. See #8529.
    */
    /*
    ** 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.testengine;

    import java.io.*;
    import java.util.*;

    import org.junit.platform.commons.util.*;
    import org.junit.platform.engine.*;
    import org.junit.platform.engine.support.hierarchical.*;

    import com.goldencode.util.*;

    /**
     * The {@link NoopDescriptor} does nothing.
     */
    public class NoopDescriptor
    implements Node<FWDEngineExecutionContext>,
               TestDescriptor,
               Printable,
               Externalizable
    {

       /** This descriptor display name */
       private String displayName;

       /** The descriptor unique ID */
       private UniqueId uniqueId;

       /** The parent descriptor or {@code null} if this is the root (test engine) descriptor */
       protected TestDescriptor parent;

       /**
        * The constructor.
        *
        * @param uniqueId
        *        the descriptor unique ID
        * @param displayName
        *        the descriptor display name
        */
       public NoopDescriptor(final UniqueId uniqueId, final String displayName)
       {
          this.displayName = displayName;
          this.uniqueId = uniqueId;
       }

       /**
        * Add a <em>child</em> to this descriptor.
        *
        * @param descriptor the child to add to this descriptor; never {@code null}
        */
       @Override
       public void addChild(TestDescriptor descriptor)
       {
          // Default is the terminal node implementation, must be re-defined for branch nodes
          throw new RuntimeException("Not supported");
       }

       /**
        * Indicates whether some other object is "equal to" this one.
        * <p>
        * The {@code equals} method implements an equivalence relation
        * on non-null object references:
        * <ul>
        * <li>It is <i>reflexive</i>: for any non-null reference value
        * {@code x}, {@code x.equals(x)} should return
        * {@code true}.
        * <li>It is <i>symmetric</i>: for any non-null reference values
        * {@code x} and {@code y}, {@code x.equals(y)}
        * should return {@code true} if and only if
        * {@code y.equals(x)} returns {@code true}.
        * <li>It is <i>transitive</i>: for any non-null reference values
        * {@code x}, {@code y}, and {@code z}, if
        * {@code x.equals(y)} returns {@code true} and
        * {@code y.equals(z)} returns {@code true}, then
        * {@code x.equals(z)} should return {@code true}.
        * <li>It is <i>consistent</i>: for any non-null reference values
        * {@code x} and {@code y}, multiple invocations of
        * {@code x.equals(y)} consistently return {@code true}
        * or consistently return {@code false}, provided no
        * information used in {@code equals} comparisons on the
        * objects is modified.
        * <li>For any non-null reference value {@code x},
        * {@code x.equals(null)} should return {@code false}.
        * </ul>
        * <p>
        * The {@code equals} method for class {@code Object} implements
        * the most discriminating possible equivalence relation on objects;
        * that is, for any non-null reference values {@code x} and
        * {@code y}, this method returns {@code true} if and only
        * if {@code x} and {@code y} refer to the same object
        * ({@code x == y} has the value {@code true}).
        * <p>
        * Note that it is generally necessary to override the {@code hashCode}
        * method whenever this method is overridden, so as to maintain the
        * general contract for the {@code hashCode} method, which states
        * that equal objects must have equal hash codes.
        *
        * @param  obj   the reference object with which to compare.
        *
        * @return {@code true} if this object is the same as the obj
        *         argument; {@code false} otherwise.
        *
        * @see    #hashCode()
        * @see    java.util.HashMap
        */
       @Override
       public final boolean equals(Object obj)
       {
          // Test descriptors are compared by their unique IDs.
          if (obj == null)
          {
             return false;
          }

          if (this.getClass() != obj.getClass())
          {
             return false;
          }

          return uniqueId.equals(((TestDescriptor) obj).getUniqueId());
       }

       /**
        * Execute the <em>behavior</em> of this node.
        *
        * <p>Containers typically do not implement this method since the
        * {@link HierarchicalTestEngine} handles execution of their children.
        *
        * <p>The supplied {@code dynamicTestExecutor} may be used to submit
        * additional dynamic tests for immediate execution.
        *
        * <p>The default implementation returns the supplied {@code context} unmodified.
        *
        * @param context the context to execute in
        * @param dynamicTestExecutor the executor to submit dynamic tests to
        * @return the new context to be used for children of this node and for the
        * <em>after</em> behavior of the parent of this node, if any
        * @see #before
        * @see #after
        */
       @Override
       public FWDEngineExecutionContext execute(FWDEngineExecutionContext context,
                                                DynamicTestExecutor dynamicTestExecutor)
       throws Exception
       {
          // Instances of this very class are created in case of failed test engine initialization.
          // The tests in this case must always fail.
          throw new Exception("Test engine was not initialized.");
       }

       /**
        * Find the descriptor with the supplied unique ID.
        * <p>
        * The search algorithm begins with this descriptor and then searches
        * through its descendants.
        *
        * @param id the {@code UniqueId} to search for; never {@code null}
        */
       @Override
       public Optional<? extends TestDescriptor> findByUniqueId(final UniqueId id)
       {
          return Optional.of(this.uniqueId.equals(id) ? this : null);
       }

       /**
        * Get the immutable set of <em>children</em> of this descriptor.
        *
        * @return the set of children of this descriptor; neither {@code null}
        *         nor mutable, but potentially empty
        *
        * @see    #getDescendants()
        */
       @Override
       public Set<? extends TestDescriptor> getChildren()
       {
          return Collections.emptySet();
       }

       /**
        * Get the display name for this descriptor.
        * <p>
        * A <em>display name</em> is a human-readable name for a test or
        * container that is typically used for test reporting in IDEs and build
        * tools. Display names may contain spaces, special characters, and emoji,
        * and the format may be customized by {@link TestEngine TestEngines} or
        * potentially by end users as well. Consequently, display names should
        * never be parsed; rather, they should be used for display purposes only.
        *
        * @return the display name for this descriptor; never {@code null} or blank
        *
        * @see    #getSource()
        */
       @Override
       public String getDisplayName()
       {
          return displayName;
       }

       /**
        * Get the <em>parent</em> of this descriptor, if available.
        */
       @Override
       public Optional<TestDescriptor> getParent()
       {
          return Optional.ofNullable(parent);
       }

       /**
        * Get the {@linkplain TestSource source} of the test or container described
        * by this descriptor, if available.
        *
        * @see TestSource
        */
       @Override
       public Optional<TestSource> getSource()
       {
          return Optional.empty();
       }

       /**
        * Get the set of {@linkplain TestTag tags} associated with this descriptor.
        *
        * @return the set of tags associated with this descriptor; never {@code null}
        *         but potentially empty
        *
        * @see    TestTag
        */
       @Override
       public Set<TestTag> getTags()
       {
          // tags are not used in FWD test engine currently
          return Collections.emptySet();
       }

       /**
        * Determine the {@link org.junit.platform.engine.TestDescriptor.Type} of this descriptor.
        *
        * @return the descriptor type; never {@code null}.
        *
        * @see    #isContainer()
        * @see    #isTest()
        */
       @Override
       public Type getType()
       {
          // Default value, test containers must re-define this method
          return Type.TEST;
       }

       /**
        * Get the unique identifier (UID) for this descriptor.
        * <p>
        * Uniqueness must be guaranteed across an entire test plan,
        * regardless of how many engines are used behind the scenes.
        *
        * @return the {@code UniqueId} for this descriptor; never {@code null}
        */
       @Override
       public final UniqueId getUniqueId()
       {
          return this.uniqueId;
       }

       /**
        * Returns a hash code value for the object. This method is
        * supported for the benefit of hash tables such as those provided by
        * {@link java.util.HashMap}.
        * <p>
        * The general contract of {@code hashCode} is:
        * <ul>
        * <li>Whenever it is invoked on the same object more than once during
        * an execution of a Java application, the {@code hashCode} method
        * must consistently return the same integer, provided no information
        * used in {@code equals} comparisons on the object is modified.
        * This integer need not remain consistent from one execution of an
        * application to another execution of the same application.
        * <li>If two objects are equal according to the {@code equals(Object)}
        * method, then calling the {@code hashCode} method on each of
        * the two objects must produce the same integer result.
        * <li>It is <em>not</em> required that if two objects are unequal
        * according to the {@link java.lang.Object#equals(java.lang.Object)}
        * method, then calling the {@code hashCode} method on each of the
        * two objects must produce distinct integer results.  However, the
        * programmer should be aware that producing distinct integer results
        * for unequal objects may improve the performance of hash tables.
        * </ul>
        * <p>
        * As much as is reasonably practical, the hashCode method defined by
        * class {@code Object} does return distinct integers for distinct
        * objects. (This is typically implemented by converting the internal
        * address of the object into an integer, but this implementation
        * technique is not required by the
        * Java&trade; programming language.)
        *
        * @return a hash code value for this object.
        *
        * @see    java.lang.Object#equals(java.lang.Object)
        * @see    java.lang.System#identityHashCode
        */
       @Override
       public final int hashCode()
       {
          return uniqueId.hashCode();
       }

       /**
        * Print all class-specific fields.
        *
        * @param printer
        *        the string printer to print into
        */
       @Override
       public void print(PrintHelper printer)
       {
          printer.print(uniqueId);
          printer.print(displayName);

          if (parent != null)
          {
             printer.print(parent.getDisplayName());
          }
       }

       /**
        * The object implements the readExternal method to restore its
        * contents by calling the methods of DataInput for primitive
        * types and readObject for objects, strings and arrays.  The
        * readExternal method must read the values in the same sequence
        * and with the same types as were written by writeExternal.
        *
        * @param     in the stream to read data from in order to restore the object
        *
        * @exception IOException if I/O errors occur
        * @exception ClassNotFoundException If the class for an object being
        *            restored cannot be found.
        */
       @Override
       public void readExternal(ObjectInput in)
       throws IOException,
              ClassNotFoundException
       {
          uniqueId = (UniqueId) in.readObject();
          displayName = (String) in.readObject();
       }

       /**
        * Remove a <em>child</em> from this descriptor.
        *
        * @param descriptor the child to remove from this descriptor; never
        *        {@code null}
        */
       @Override
       public void removeChild(TestDescriptor descriptor)
       {
          throw new RuntimeException("Not supported");
       }

       /**
        * Remove this non-root descriptor from its parent and remove all the
        * children from this descriptor.
        * <p>
        * If this method is invoked on a {@linkplain #isRoot root} descriptor,
        * this method must throw a {@link org.junit.platform.commons.JUnitException JUnitException}
        * explaining that a root cannot be removed from the
        * hierarchy.
        */
       @Override
       public void removeFromHierarchy()
       {
          Preconditions.condition(!isRoot(), "cannot remove the root of a hierarchy");

          parent.removeChild(this);
          setParent(null);
       }

       /**
        * Set the <em>parent</em> of this descriptor.
        *
        * @param parent the new parent of this descriptor; may be {@code null}.
        */
       @Override
       public void setParent(final TestDescriptor parent)
       {
          this.parent = parent;
       }

       /**
        * Returns a string representation of the object. In general, the
        * {@code toString} method returns a string that
        * "textually represents" this object. The result should
        * be a concise but informative representation that is easy for a
        * person to read.
        * It is recommended that all subclasses override this method.
        * <p>
        * The {@code toString} method for class {@code Object}
        * returns a string consisting of the name of the class of which the
        * object is an instance, the at-sign character `{@code @}', and
        * the unsigned hexadecimal representation of the hash code of the
        * object. In other words, this method returns a string equal to the
        * value of:
        * <blockquote>
        * <pre>
        * getClass().getName() + '@' + Integer.toHexString(hashCode())
        * </pre></blockquote>
        *
        * @return a string representation of the object.
        */
       @Override
       public String toString()
       {
          return asString();
       }

       /**
        * The object implements the writeExternal method to save its contents
        * by calling the methods of DataOutput for its primitive values or
        * calling the writeObject method of ObjectOutput for objects, strings,
        * and arrays.
        *
        * @serialData Overriding methods should use this tag to describe
        *             the data layout of this Externalizable object.
        *             List the sequence of element types and, if possible,
        *             relate the element to a public/protected field and/or
        *             method of this Externalizable class.
        *
        * @param      out the stream to write the object to
        *
        * @exception  IOException Includes any I/O exceptions that may occur
        */
       @Override
       public void writeExternal(ObjectOutput out)
       throws IOException
       {
          out.writeObject(uniqueId);
          out.writeObject(displayName);
       }

    }