# AbstractFWDTestDescriptor.java

    /*
    ** Module   : AbstractFWDTestDescriptor.java
    ** Abstract : Common accessor for all test descriptors
    **
    ** Copyright (c) 2023-2024, Golden Code Development Corporation.
    **
    ** -#- -I- --Date-- ---------------------------------Description---------------------------------
    ** 001 VVT 20230318 Created initial version.
    ** 002 VVT 20230412 OEUnit support added. See #6237.
    ** 003 VVT 20230512 Fixed error propagation. (See #3827-350). Source formatting fixed.
    **                  Tags support added to FWD engine (FWD extension).
    ** 004 VVT 20240321 Javadocs updated for getTestObject(). See #8406.
    ** 005 VVT 20240408 Minor style fixes. See #8406-70.
    ** 006 VVT 20240614 This class inheritance updated to match the change in NoopDescriptor. See #8529.
    ** 007 VVT 20240718 checkInstance() method lifted here from FWDProcedureTestDescriptor. See #8874.
    */
    /*
    ** 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.lang.reflect.*;
    import java.util.*;

    import org.junit.platform.engine.*;
    import org.opentest4j.*;

    import com.goldencode.p2j.testengine.api.*;
    import com.goldencode.p2j.util.*;

    /**
     * This class provides common functions for all FWD test descriptors:
     *
     * <li>Stores unique ID, display name and parent reference.
     * <li>Serialization: FWD test descriptors travel over network, so they must be serializable.
     * <li>Implements {@link Node} interface: all methods are passed to a proxy to be executed on the server.
     */
    public abstract class AbstractFWDTestDescriptor
    extends NoopDescriptor
    {

       /** The tags */
       private Set<TestTag> tags;

       /**
        * Extract set of {@link TestTag} from tag-related annotations.
        *
        * @param o
        *        the source of tag annotations
        *
        * @return see above
        */
       protected final static Set<TestTag> getTags(final AnnotatedElement o)
       {
          // A single Tag annotation: test for the Tag
          final Tag tagAnno = o.getAnnotation(Tag.class);
          if (tagAnno != null)
          {
             final Set<TestTag> methodTags = new HashSet<>();
             methodTags.add(TestTag.create(tagAnno.value()));
             return methodTags;
          }

          // In case of repeated Tag annotation, Java compiler
          // creates a single Tags annotation (and no Tag annotations)
          final Tags tagsAnno = o.getAnnotation(Tags.class);
          if (tagsAnno != null)
          {
             final Set<TestTag> methodTags = new HashSet<>();
             for (final Tag t : tagsAnno.value())
             {
                methodTags.add(TestTag.create(t.value()));
             }
             return methodTags;
          }

          // Neither Tag nor Tags annotation is present
          return Collections.emptySet();
       }

       /**
        * The constructor.
        *
        * @param uniqueId
        *        the descriptor unique ID
        * @param displayName
        *        the descriptor display name
        * @param tags
        *        the tag set
        */
       public AbstractFWDTestDescriptor(final UniqueId uniqueId,
                                        final String displayName,
                                        final Set<TestTag> tags)
       {
          super(uniqueId, displayName);

          this.tags = tags;
       }

       /**
        * Default constructor. Must be used internally for serialization only.
        */
       protected AbstractFWDTestDescriptor()
       {
          this(null, null, null);
       }

       /**
        * Execute the <em>after</em> behavior of this node.
        * <p>
        * This method will be called once <em>after</em> {@linkplain #execute execution}
        * of this node.
        *
        * @param context
        *        the context to execute in
        */
       @Override
       public void after(final FWDEngineExecutionContext context)
       throws ErrorConditionException,
              AssertionFailedError
       {
          context.unitTestSupport.after(getUniqueId());
       }

       /**
        * Execute the <em>after</em> behavior of this node implementation.
        * <p>
        * This method will be called once <em>after</em> {@linkplain #executeImpl() execution}
        * of this node.
        *
        * @throws ErrorConditionException
        *         remote code may throw this
        */
       @SuppressWarnings("static-method")
       public void afterImpl()
       throws ErrorConditionException
       {
          // no-op
       }

       /**
        * Execute the <em>before</em> behavior of this node.
        * <p>
        * This method will be called once <em>before</em> {@linkplain #execute execution}
        * of this node.
        *
        * @param  context
        *         the context to execute in
        *
        * @return the new context to be used for children of this node; never
        *         {@code null}
        */
       @Override
       public FWDEngineExecutionContext before(FWDEngineExecutionContext context)
       throws ErrorConditionException,
              AssertionFailedError
       {
          context.unitTestSupport.before(getUniqueId());
          return context;
       }

       /**
        * Execute the <em>before</em> behavior of this node implementation.
        * <p>
        * This method will be called once <em>before</em> {@linkplain #executeImpl() execution}
        * of this node.
        *
        * @throws ErrorConditionException
        *         remote code may throw this
        */
       @SuppressWarnings("static-method")
       public void beforeImpl()
       throws ErrorConditionException
       {
          // no-op
       }

       /**
        * Clean up the supplied {@code context} after execution.
        * <p>
        * Reset the test class instance.
        *
        * @param context
        *        the context to execute in
        *
        * @see   #prepare
        */
       @Override
       public void cleanUp(final FWDEngineExecutionContext context)
       throws ErrorConditionException,
              AssertionFailedError
       {
          context.unitTestSupport.cleanUp(getUniqueId());
       }

       /**
        * Clean up the supplied {@code context} after execution implementation.
        * <p>
        * Reset the test class instance.
        *
        * @throws ErrorConditionException
        *         remote code may throw this
        *
        * @see    #prepare
        */
       public void cleanUpImpl()
       throws ErrorConditionException
       {
          // no-op
       }

       /**
        * 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.
        *
        * @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
        */
       @Override
       public FWDEngineExecutionContext execute(final FWDEngineExecutionContext context,
                                                final DynamicTestExecutor dynamicTestExecutor)
       throws ErrorConditionException,
              AssertionFailedError
       {
          context.unitTestSupport.execute(getUniqueId());
          return context;
       }

       /**
        * Execute the implementation <em>behavior</em> of this node.
        *
        * @throws ErrorConditionException
        *         remote code may throw this
        */
       @SuppressWarnings("static-method")
       public void executeImpl()
       throws ErrorConditionException
       {
          // no-op
       }

       /**
        * 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()
       {
          return tags;
       }

       /**
        * Prepare the supplied {@code context} prior to execution.
        * <p>
        * Create test class instance.
        *
        * @see #cleanUp
        */
       @Override
       public FWDEngineExecutionContext prepare(final FWDEngineExecutionContext context)
       throws ErrorConditionException,
              AssertionFailedError
       {
          context.unitTestSupport.prepare(getUniqueId());
          return context;
       }

       /**
        * Prepare the supplied {@code context} prior to execution implementation.
        *
        * @throws ErrorConditionException
        *         remote code may throw this
        * @throws AssertionFailedError
        *         legacy errors are converted to this exception
        *
        * @see    #cleanUpImpl
        */
       public void prepareImpl()
       throws ErrorConditionException
       {
          // no-op
       }

       /**
        * 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.
        */
       @SuppressWarnings("unchecked")
       @Override
       public void readExternal(ObjectInput in)
       throws IOException,
              ClassNotFoundException
       {
          super.readExternal(in);

          tags = (Set<TestTag>) in.readObject();
       }

       /**
        * 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.
        */
       @SuppressWarnings("null")
       @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
       {
          super.writeExternal(out);

          out.writeObject(tags);
       }

       /**
        * Convenience method to execute all of life-cycle methods of a kind.
        * All methods assumed having no parameters and return VOID.
        *
        * @param  methods
        *         the methods to execute, possibly empty
        *
        * @throws ErrorConditionException
        *         the first thrown by any method
        *
        * @see    #beforeImpl
        * @see    #afterImpl
        */
       protected final void callLFMethodsImpl(final List<Method> methods)
       throws ErrorConditionException
       {
          final int size = methods.size();
          if (size == 0)
          {
             return;
          }

          final Object testObject = getTestObject();
          for (int i = 0; i < size; i++)
          {
             final Method m = methods.get(i);
             callMethodImpl(m, testObject, null);
          }
       }

       /**
        * Execute list of methods implementation, collect the result.
        *
        * @param  method
        *         the method to execute
        * @param  parameterList
        *         the method call arguments or {@code null} for no arguments
        *
        * @return the array of results of each method call, the {@code null} value
        *         is used for methods returning VOID or a legacy error occurred
        *
        * @see    #executeImpl
        */
       protected BaseDataType callMethodImpl(final Method method,
                                             final CallParameter[] parameterList)
       {
          return callMethodImpl(method, getTestObject(), parameterList);
       }

       /**
        * Execute a method.
        *
        * @param  method
        *         the method to execute
        * @param  o
        *         the object to use, can be {@code null} for "static" methods.
        * @param  parameters
        *         method call parameters, {@code null} for no parameters
        *
        * @return the result of the call or {@code null} for methods returning VOID
        *         or if a legacy error was raised
        *
        * @throws ErrorConditionException
        *         by the executed legacy code
        * @throws LegacyErrorException
        *         legacy errors are not caught by this method
        */
       @SuppressWarnings("static-method")
       protected BaseDataType callMethodImpl(final Method method,
                                             final Object o,
                                             final CallParameter[] parameters)
       throws ErrorConditionException,
              LegacyErrorException
       {
          // Default is legacy class method call
          return TestExecutionSupport.callClassMethod(method, (object<?>) o, parameters);
       }

       /**
        * Get test object. The test object is either a legacy class instance if tests are implemented
        * as legacy class methods or a persistent procedure instance it tests are implemented as
        * internal procedures.
        * <p>
        * The value should be {@code null} if the test method is a static legacy class method.
        *
        * @return the test object or {@code null}
        */
       @SuppressWarnings("static-method")
       protected Object getTestObject()
       {
          return null;
       }

       /**
        * Throw error if the procedure instance is not valid.
        *
        * @param h
        *        the instance handle
        */
       protected final void checkInstance(final handle h)
       {
          if (!h._isValid())
          {
             throw new AssertionError(TextOps.substitute("Test instance &1 is invalid", getDisplayName())
                      .toStringMessage());
          }
       }

    }