text: /**
   * Licensed to Apereo under one or more contributor license agreements. See the NOTICE file
   * distributed with this work for additional information regarding copyright ownership. Apereo
   * licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use
   * this file except in compliance with the License. You may obtain a copy of the License at the
   * following location:
   *
   * <p>http://www.apache.org/licenses/LICENSE-2.0
   *
   * <p>Unless required by applicable law or agreed to in writing, software distributed under the
   * License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
   * express or implied. See the License for the specific language governing permissions and
   * limitations under the License.
   */
  package org.apereo.portal.permission.dao;
  
  import java.util.List;
  import org.apereo.portal.permission.IPermissionActivity;
  import org.apereo.portal.permission.IPermissionOwner;
  
  /**
   * IPermissionOwnerDao represents an interface for retrieving and persisting permission owners.
   *
   * @since 3.3
   */
  public interface IPermissionOwnerDao {
  
      /**
       * Retrieve the permission owner with the specified unique ID.
       *
       * @param id
       * @return
       */
      public IPermissionOwner getPermissionOwner(long id);
  
      /**
       * Retrieve the permission owner with the specified functional name.
       *
       * @param fname
       * @return
       */
      public IPermissionOwner getPermissionOwner(String fname);
  
      /**
       * Retrieve the permission owner associated with the supplied functional name. If no matching
       * permission owner can be found, create a new permission owner instance with the supplied
       * functional name. @Param name Name of the permission owner
       *
       * @param fname functional name of the desired permission owner
       * @return
       */
      public IPermissionOwner getOrCreatePermissionOwner(String name, String fname);
  
      /**
       * Retrieve a list of all known permission owners from the data store.
       *
       * @return
       */
      public List<IPermissionOwner> getAllPermissionOwners();
  
      /**
       * Persist a permission owner to the data layer, creating or updating the owner as appropriate.
       *
       * @param owner
       * @return
       */
      public IPermissionOwner saveOwner(IPermissionOwner owner);
  
      /**
       * Retrieve a permission activity by unique ID.
       *
       * @param id
       * @return
       */
      public IPermissionActivity getPermissionActivity(long id);
  
      /**
       * Retrieve a permission activity under the specified permission owner with the provided
       * activity functional name.
       *
       * @param ownerId unique ID of the desired activity's owner
       * @param activityFname functional name of the desired activity
       * @return
       */
      public IPermissionActivity getPermissionActivity(long ownerId, String activityFname);
  
      /**
       * Retrieve a permission activity under the specified permission owner with the provided
       * activity functional name.
       *
       * @param ownerFname functional name of the desired activity's owner
       * @param activityFname functional name of the activity itself
       * @return
       */
      public IPermissionActivity getPermissionActivity(String ownerFname, String activityFname);
  
      /**
       * Retrieve the permission activity associated with the supplied functional name, under the
       * specified permission owner. If no matching activity can be found, create a new permission
       * activity instance with the supplied owner and activity functional name.
       *
       * @param owner permission owner
       * @param fname activity fname
       * @return
       */
      public IPermissionActivity getOrCreatePermissionActivity(
              IPermissionOwner owner, String name, String fname, String targetProviderKey);
  
      /**
       * Persist a permission activity to the data layer, creating or updating the activity as
       * appropriate.
       *
       * @param activity
       * @return
       */
      public IPermissionActivity savePermissionActivity(IPermissionActivity activity);
  }
  