# SOAPFactory.java

    /*
    ** Module   : SOAPFactory.java
    ** Abstract : Factory of SOAP objects.
    **
    ** Copyright (c) 2013-2023, Golden Code Development Corporation.
    **
    ** -#- -I- --Date-- --------------------------------Description-----------------------------------
    ** 001 CA  20130216 Created initial version.
    ** 002 CA  20130918 Added widget-pool support. The pool name must be validated before anything
    **                  else, and a null name means the default pool is used.
    ** 003 CA  20130927 Fixed CREATE statement calls.
    ** 004 CA  20131223 Added APIs to create SOAPFault and SOAPFaultDetail resources.
    ** 005 GES 20140122 Moved the throwError() logic into ErrorManager so that it can be shared as
    **                  common code.
    ** 006 CA  20230724 Further reduce context-local usage.
    */
    /*
    ** 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.util;

    /**
     * Adds support for the {@link #createSOAPHeader CREATE SOAP-HEADER} and
     * {@link #createSOAPHeaderEntry(handle) CREATE SOAP-HEADER-ENTRYREF} language statements.
     */
    public class SOAPFactory
    {
       /**
        * Create a SOAP-HEADER object and save it in the given handle.
        *
        * @param    h
        *           A handle variable, field or class member where the SOAP-HEADER will be saved.
        */
       public static void createSOAPHeader(handle h)
       {
          createSOAPHeader(h, (character) null);
       }

       /**
        * Create a SOAP-HEADER object, save it in the given handle and register it in the given
        * named widget-pool.
        *
        * @param    h
        *           A handle variable, field or class member where the SOAP-HEADER will be saved.
        * @param    pool
        *           The name of the widget pool. <code>null</code> if the unnamed pool must be used.
        */
       public static void createSOAPHeader(handle h, String pool)
       {
          createSOAPHeader(h, (pool == null ? null : new character(pool)));
       }

       /**
        * Create a SOAP-HEADER object, save it in the given handle and register it in the given
        * named widget-pool.
        *
        * @param    h
        *           A handle variable, field or class member where the SOAP-HEADER will be saved.
        * @param    pool
        *           The name of the widget pool. <code>null</code> if the unnamed pool must be used.
        */
       public static void createSOAPHeader(handle h, character pool)
       {
          // validate widget pool before anything else!!!
          if (!WidgetPool.validWidgetPool(pool))
          {
             return;
          }

          SOAPHeaderImpl res = new SOAPHeaderImpl();
          h.assign(res);

          res.addToPool(pool);
       }

       /**
        * Create a SOAP-HEADER-ENTRYREF object and save it in the given handle.
        *
        * @param    h
        *           A handle variable, field or class member where the SOAP-HEADER-ENTRYREF will be
        *           saved.
        */
       public static void createSOAPHeaderEntry(handle h)
       {
          createSOAPHeaderEntry(h, (character) null);
       }

       /**
        * Create a SOAP-HEADER-ENTRYREF object, save it in the given handle and register it in the
        * given named widget-pool.
        *
        * @param    h
        *           A handle variable, field or class member where the SOAP-HEADER-ENTRYREF will be
        *           saved.
        * @param    pool
        *           The name of the widget pool. <code>null</code> if the unnamed pool must be used.
        */
       public static void createSOAPHeaderEntry(handle h, String pool)
       {
          createSOAPHeaderEntry(h, (pool == null ? null : new character(pool)));
       }

       /**
        * Create a SOAP-HEADER-ENTRYREF object, save it in the given handle and register it in the
        * given named widget-pool.
        *
        * @param    h
        *           A handle variable, field or class member where the SOAP-HEADER-ENTRYREF will be
        *           saved.
        * @param    pool
        *           The name of the widget pool. <code>null</code> if the unnamed pool must be used.
        */
       public static void createSOAPHeaderEntry(handle h, character pool)
       {
          // validate widget pool before anything else!!!
          if (!WidgetPool.validWidgetPool(pool))
          {
             return;
          }

          SOAPHeaderEntryImpl res = new SOAPHeaderEntryImpl();
          h.assign(res);

          res.addToPool(pool);
       }

       /**
        * Create a new {@link SOAPFaultDetailImpl} resource using the given XML payload.
        *
        * @param    payload
        *           The XML payload.
        *
        * @return   A {@link SOAPFaultDetailImpl} for the given XML payload.
        */
       static SOAPFaultDetailImpl createSOAPFaultDetail(String payload)
       {
          // this resource is not pooled

          SOAPFaultDetailImpl res = new SOAPFaultDetailImpl(payload);

          return res;
       }

       /**
        * Create a new {@link SOAPFaultImpl} resource.
        *
        * @param    faultActor
        *           The SOAP fault actor.
        * @param    faultCode
        *           The SOAP fault code.
        * @param    faultString
        *           The SOAP fault string.
        * @param    soapFaultDetail
        *           The {@link SOAPFaultDetailImpl SOAP fault detail}; may be <code>null</code>.
        *
        * @return   See above.
        */
       static SOAPFaultImpl createSOAPFault(String faultActor,
                                            String faultCode,
                                            String faultString,
                                            SOAPFaultDetailImpl soapFaultDetail)
       {
          // this resource is not pooled.

          SOAPFaultImpl res = new SOAPFaultImpl(faultActor, faultCode, faultString, soapFaultDetail);

          return res;
       }

       /**
        * Throws an {@link ErrorConditionException} or sets the {@link ErrorManager}'s {@code pending}
        * flag to {@code true}, if we are in silent error mode.
        *
        * @param    caller
        *           The name of the resource calling this API.
        * @param    target
        *           The name of the resource's method or attribute which needs to raise an ERROR
        *           condition or set the ERROR-STATUS:ERROR flag to {@code true}.
        */
       static void throwError(String caller, String target)
       {
          final String msg = "%s requires a valid %s!";
          ErrorManager.noRecordOrThrowError(String.format(msg, caller, target));
       }
    }