# AbstractResource.java

    /*
    ** Module   : AbstractResource.java
    ** Abstract : A partial implementation of Resource interface that enforces
    **            some coding requirements for all abstract resource plugins.
    **
    ** Copyright (c) 2004-2023, Golden Code Development Corporation.
    **
    ** -#- -I- --Date-- --JPRM-- ----------------Description-----------------
    ** 001 NVS 20050208   @19706 Created the initial version.
    ** 002 NVS 20050412   @20686 Added new methods to work with the thread
    **                           local reference to the current Rights object
    **                           for the time of expression evaluation.
    ** 003 NVS 20050421   @21268 Passing a generic Object between compute and
    **                           evaluate calls and the resource plugin's
    **                           library of exported variables and methods
    **                           instead of Rights. This allows arbitrary
    **                           plugin's object to serve as a convenient
    **                           data linkage.
    ** 004 NVS 20050524   @21269 This abstract class now implements the Scope
    **                           interface which is required by the new Expression
    **                           Engine. The scopes are nested so that
    **                           this plugin's scope has the Security Manager'
    **                           s scope as its parent.
    ** 005 NVS 20090824   @43726 Implemented empty init() method. Resource plugins
    **                           may override it, however.
    ** 006 CA  20091026   @44195 Added getPermissions - it computes the permissions
    **                           for the specified subject and resource instance
    **                           name.
    ** 007 SIY 20100418   @44822 Minor cleanups. Added refresh() method.
    ** 008 HC  20200313          Javadoc fixes.
    ** 009 HC  20230427          Implemented management for file-system resource. This includes Admin
    **                           and server directory changes.
    ** 010 CA  20230531          Moved the scope state from the resolver to the actual scope; this avoids using
    **                           a WeakHashMap to determine the scope's state associated with a certain resolver,
    **                           as long as a single resolver instance uses that scope (common for conversion).
    */
    /*
    ** 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.security;

    import com.goldencode.expr.*;
    import com.goldencode.p2j.admin.AdminAccountExtension;

    import java.util.function.*;

    /**
     * This abstract class partially implements the Resource interface.
     */
    public abstract class AbstractResource
    extends Scope
    implements Resource
    {
       /** per thread reference to the Rights context */
       protected static ThreadLocal<Object> objectPointer = null;

       /** reference to the attached instance of SecurityManager */
       protected SecurityManager sm = null;

       /** resource index assigned during resource registration */
       protected int resourceIndex = -1;

       static
       {
          objectPointer = new ThreadLocal<Object>();
       }

       /**
        * Notifies the plugin about the instance of the Security Manager
        * to communicate with.
        *
        * @param  sm
        *         specifies an instance of <code>SecurityManager</code> this
        *         plugin should communicate with
        */
       public final void attach(SecurityManager sm)
       {
          this.sm = sm;
          init();
       }

       /**
        * Gives chance to the plugin to initialize when all accounts are created.
        * This method should be overridden by resource plugin, if init is
        * required.
        */
       public void init()
       {
       }

       /**
        * Notifies the plugin that the resource type has been assigned a numeric
        * value.
        *
        * @param  resourceIndex
        *         specifies the registration number for the resource
        */
       public final void registeredAs(int resourceIndex)
       {
          this.resourceIndex = resourceIndex;
       }

       /**
        * Returns a bi-predicate allowing to match ACLs based on a supplied resource instance name. The plugin
        * may choose not to provide its own matcher, in which case the method should return {@code null}.
        *
        * @return  A bi-predicate or {@code null}.
        */
       public BiPredicate<AccessControlList, String> getACLMatcher()
       {
          return null;
       }

       /**
        * Returns the string representation of this plugin.
        *
        * @return string describing this plugin
        */
       public String toString()
       {
          return this.getTypeName() + " resource plugin";
       }

       /**
        * Gets the parent scope for this scope.
        * Plugins always have SecurityManager as the parent scope.
        *
        * @return parent <code>Scope</code> object, which is
        *         <code>SecurityManager</code>
        */
       public final Scope getEnclosingScope()
       {
          return sm;
       }

       /**
        * Returns the plugin's exported variables and functions.
        * <p>
        * This implementation exports no library. Plugins that require exported
        * variables should override this method.
        *
        * @return plugin's instance of a library class for symbol resolution or
        *         <code>null</code> if there is nothing to export
        */
       public Object getLibrary()
       {
          return null;
       }

       /**
        * Stores the reference to the passed Rights object into a thread local
        * storage temporarily for the use in the library methods during the
        * expression evaluation.
        *
        * @param link
        *        reference to an arbitrary Object that serves as a data sharing
        *        link for the expression evaluation.
        */
       public final void associate(Object link)
       {
          objectPointer.set(link);
       }

       /**
        * Nullifies the reference to the Rights object in the thread local
        * storage.
        */
       public final void disassociate()
       {
          objectPointer.set(null);
       }

       /**
        * Returns the reference to the currently associated link object.
        *
        * @return  See above.
        */
       protected final Object getLink()
       {
          return objectPointer.get();
       }

       /**
        * The method is responsible for computing the permissions for the given
        * instance name; the permissions are the ones valid for the specified
        * subject ID.
        *
        * @param    subject
        *           The subject ID for which the permissions needs to be computed.
        * @param    instanceName
        *           The instance name for which the permissions are checked.
        *
        * @return   The permissions for the given instance name, valid for the
        *           specified subject ID.
        */
       public Rights getPermissions(String subject, String instanceName)
       {
          throw new RuntimeException("Method is not implemented");
       }

       /**
        * Refresh request to plugin.
        *
        * @param   ext
        *          A valid instance of the admin plugin.
        */
       public void refresh(AdminAccountExtension ext)
       {
       }
    }