/*
    * Copyright 2008 The Kuali Foundation
    *
    * Licensed under the Educational Community 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
    *
    * http://www.opensource.org/licenses/ecl2.php
    *
   * 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.kuali.rice.kim.service;
  
  import java.util.List;
  import java.util.Map;
  
  import javax.jws.WebParam;
  import javax.jws.WebService;
  import javax.jws.soap.SOAPBinding;
  import javax.xml.bind.annotation.adapters.XmlJavaTypeAdapter;
  
  import org.kuali.rice.core.jaxb.AttributeSetAdapter;
  import org.kuali.rice.core.jaxb.MapStringStringAdapter;
  import org.kuali.rice.kim.bo.role.dto.KimResponsibilityInfo;
  import org.kuali.rice.kim.bo.role.dto.KimResponsibilityTemplateInfo;
  import org.kuali.rice.kim.bo.role.dto.ResponsibilityActionInfo;
  import org.kuali.rice.kim.bo.types.dto.AttributeSet;
  import org.kuali.rice.kim.util.KIMWebServiceConstants;
  
  /**
   * 
   * This service provides operations for determining what responsibility actions
   * a principal has and for querying about responsibility data.
   * 
   * <p>A responsibility represents an action that a principal is requested to
   * take.  This is used for defining workflow actions (such as approve, 
   * acknowledge, fyi) that the principal has the responsibility to take.  The
   * workflow engine integrates with this service to provide
   * responsibility-driven routing.
   * 
   * <p>A responsibility is very similar to a permission in a couple of ways.
   * First of all, responsibilities are always granted to a role, never assigned
   * directly to a principal or group.  Furthermore, in a similar fashion to
   * permissions, a role has the concept of a responsibility template.  The
   * responsibility template specifies what additional responsibility details
   * need to be defined when the responsibility is created.
   * 
   * <p>This service provides read-only operations.  For write operations, see
   * {@link ResponsibilityUpdateService}.
   * 
   * @see ResponsibilityUpdateService
   * 
   * @author Kuali Rice Team (rice.collab@kuali.org)
   *
   */
  @WebService(name = KIMWebServiceConstants.ResponsibilityService.WEB_SERVICE_NAME, targetNamespace = KIMWebServiceConstants.MODULE_TARGET_NAMESPACE)
  @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)
  public interface ResponsibilityService {
  
      // --------------------
      // Responsibility Methods
      // --------------------
  
      /**
       * Get the responsibility object with the given ID.
       */
      KimResponsibilityInfo getResponsibility(@WebParam(name="responsibilityId") String responsibilityId);
      
   	/** 
   	 * Return the responsibility object for the given unique combination of namespace,
   	 * component and responsibility name.
   	 */
      List<KimResponsibilityInfo> getResponsibilitiesByName( @WebParam(name="namespaceCode") String namespaceCode, 
      													   @WebParam(name="responsibilityName") String responsibilityName );
      
      KimResponsibilityTemplateInfo getResponsibilityTemplate( @WebParam(name="responsibilityTemplateId") String responsibilityTemplateId );
  
      KimResponsibilityTemplateInfo getResponsibilityTemplateByName( 
      		@WebParam(name="namespaceCode") String namespaceCode, 
  			@WebParam(name="responsibilityTemplateName") String responsibilityTemplateName );
      
      /**
       * Check whether the principal has the given responsibility within the passed qualifier.
       */
      boolean hasResponsibility( @WebParam(name="principalId") String principalId, 
      						   @WebParam(name="namespaceCode") String namespaceCode, 
      						   @WebParam(name="responsibilityName") String responsibilityName, 
      						   @WebParam(name="qualification") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet qualification, 
      						   @WebParam(name="responsibilityDetails") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet responsibilityDetails );
  
      /**
       * Check whether the principal has the given responsibility within the passed qualifier.
       */
      boolean hasResponsibilityByTemplateName( @WebParam(name="principalId") String principalId, 
      										 @WebParam(name="namespaceCode") String namespaceCode, 
     										 @WebParam(name="responsibilityTemplateName") String responsibilityTemplateName, 
     										 @WebParam(name="qualification") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet qualification, 
     										 @WebParam(name="responsibilityDetails") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet responsibilityDetails );
     
    	List<ResponsibilityActionInfo> getResponsibilityActions( @WebParam(name="namespaceCode") String namespaceCode, 
    															 @WebParam(name="responsibilityName") String responsibilityName, 
    															 @WebParam(name="qualification") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet qualification, 
    															 @WebParam(name="responsibilityDetails") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet responsibilityDetails);
    	
    	List<ResponsibilityActionInfo> getResponsibilityActionsByTemplateName( @WebParam(name="namespaceCode") String namespaceCode, 
    																		   @WebParam(name="responsibilityTemplateName") String responsibilityTemplateName,	
    																		   @WebParam(name="qualification") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet qualification, 
    																		   @WebParam(name="responsibilityDetails") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet responsibilityDetails);
    	
     /**
      * Lets the system know (mainly for UI purposes) whether this responsibility expects RoleResponsibilityAction
      * records to be given at the assignment level or are global to the responsibility.  (I.e., they apply
      * to any member assigned to the responsibility.) 
      */
    	boolean areActionsAtAssignmentLevelById( @WebParam(name="responsibilityId") String responsibilityId );
 
     /**
      * Lets the system know (mainly for UI purposes) whether this responsibility expects RoleResponsibilityAction
      * records to be given at the assignment level or are global to the responsibility.  (I.e., they apply
      * to any member assigned to the responsibility.) 
      */
    	boolean areActionsAtAssignmentLevel( @WebParam(name="responsibility") KimResponsibilityInfo responsibility );
    	
    	/**
    	 * Lookup responsibility objects.
    	 */
    	List<? extends KimResponsibilityInfo> lookupResponsibilityInfo( @WebParam(name="searchCriteria") @XmlJavaTypeAdapter(value = MapStringStringAdapter.class) Map<String,String> searchCriteria, 
    																	@WebParam(name="unbounded") boolean unbounded );
    	
    	/**
    	 * Get the role IDs associated with the given responsibility.
    	 */
    	List<String> getRoleIdsForResponsibility( @WebParam(name="responsibility") KimResponsibilityInfo responsibility, 
    											  @WebParam(name="qualification") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet qualification );
 }