/*

  * Copyright 2008-2009 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.WebMethod;

 import javax.jws.WebParam;

 import javax.jws.WebService;

 import javax.jws.soap.SOAPBinding;

 import javax.servlet.http.HttpServletRequest;

 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.entity.dto.KimEntityDefaultInfo;

 import org.kuali.rice.kim.bo.entity.dto.KimEntityInfo;

 import org.kuali.rice.kim.bo.entity.dto.KimPrincipalInfo;

 import org.kuali.rice.kim.bo.group.dto.GroupInfo;

 import org.kuali.rice.kim.bo.reference.dto.AddressTypeInfo;

 import org.kuali.rice.kim.bo.reference.dto.AffiliationTypeInfo;

 import org.kuali.rice.kim.bo.reference.dto.CitizenshipStatusInfo;

 import org.kuali.rice.kim.bo.reference.dto.EmailTypeInfo;

 import org.kuali.rice.kim.bo.reference.dto.EmploymentStatusInfo;

 import org.kuali.rice.kim.bo.reference.dto.EmploymentTypeInfo;

 import org.kuali.rice.kim.bo.reference.dto.EntityNameTypeInfo;

 import org.kuali.rice.kim.bo.reference.dto.EntityTypeInfo;

 import org.kuali.rice.kim.bo.reference.dto.ExternalIdentifierTypeInfo;

 import org.kuali.rice.kim.bo.reference.dto.PhoneTypeInfo;

 import org.kuali.rice.kim.bo.role.dto.KimPermissionInfo;

 import org.kuali.rice.kim.bo.role.dto.KimResponsibilityInfo;

 import org.kuali.rice.kim.bo.role.dto.PermissionAssigneeInfo;

 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 is the front end for the KIM module.  Clients of KIM should access this service from

  * their applications.  If KIM is not running on the same machine (VM) as the application

  * (as would be the case with a standalone Rice server), then this service should be implemented

  * locally within the application and access the core KIM services

  * (Authentication/Authorization/Identity/Group) via the service bus.

  *

  *  For efficiency, implementations of this interface should add appropriate caching of

  *  the information retrieved from the core services for load and performance reasons.

  *

  *  Most of the methods on this interface are straight pass-thrus to methods on the four core services.

  *

  * @author Kuali Rice Team (rice.collab@kuali.org)

  *

  */

 @WebService(name = KIMWebServiceConstants.IdentityManagementService.WEB_SERVICE_NAME, targetNamespace = KIMWebServiceConstants.MODULE_TARGET_NAMESPACE)

 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED)

 public interface IdentityManagementService {

         // *******************************

         // IdentityService

         // *******************************

         KimPrincipalInfo getPrincipal(@WebParam(name="principalId") String principalId);

         KimPrincipalInfo getPrincipalByPrincipalName(@WebParam(name="principalName") String principalName);

         KimPrincipalInfo getPrincipalByPrincipalNameAndPassword(

                         @WebParam(name="principalName") String principalName,

                         @WebParam(name="password") String password

         );

         KimEntityDefaultInfo getEntityDefaultInfo( @WebParam(name="entityId") String entityId );

         KimEntityDefaultInfo getEntityDefaultInfoByPrincipalId( @WebParam(name="principalId") String principalId );

         KimEntityDefaultInfo getEntityDefaultInfoByPrincipalName( @WebParam(name="principalName") String principalName );

         List<? extends KimEntityDefaultInfo> lookupEntityDefaultInfo(

                         @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)

                         @WebParam(name="searchCriteria") Map<String,String> searchCriteria,

                         @WebParam(name="unbounded") boolean unbounded

         );

         int getMatchingEntityCount( @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)

                         @WebParam(name="searchCriteria") Map<String,String> searchCriteria );

         //KimEntityPrivacyPreferencesInfo getEntityPrivacyPreferences(String entityId);

         KimEntityInfo getEntityInfo( @WebParam(name="entityId") String entityId );

         KimEntityInfo getEntityInfoByPrincipalId( @WebParam(name="principalId") String principalId );

         KimEntityInfo getEntityInfoByPrincipalName( @WebParam(name="principalName") String principalName );

         List<KimEntityInfo> lookupEntityInfo(

                         @XmlJavaTypeAdapter(value = MapStringStringAdapter.class)

                         @WebParam(name = "searchCriteria") Map<String,String> searchCriteria,

                         @WebParam(name="unbounded") boolean unbounded

         );

         AddressTypeInfo getAddressType( @WebParam(name="code") String code );

         AffiliationTypeInfo getAffiliationType( @WebParam(name="code")String code );

         CitizenshipStatusInfo getCitizenshipStatus( @WebParam(name="code") String code );

         EmailTypeInfo getEmailType( @WebParam(name="code") String code );

         EmploymentStatusInfo getEmploymentStatus( @WebParam(name="code") String code );

         EmploymentTypeInfo getEmploymentType( @WebParam(name="code") String code );

         EntityNameTypeInfo getEntityNameType( @WebParam(name="code") String code );

         EntityTypeInfo getEntityType( @WebParam(name="code") String code );

         ExternalIdentifierTypeInfo getExternalIdentifierType( @WebParam(name="code") String code );

         PhoneTypeInfo getPhoneType( @WebParam(name="code") String code );

         // *******************************

         // GroupService

         // *******************************

         GroupInfo getGroup(@WebParam(name="groupId") String groupId);

     GroupInfo getGroupByName(

                     @WebParam(name="namespaceCode") String namespaceCode,

                     @WebParam(name="groupName") String groupName

     );

     List<String> getParentGroupIds( @WebParam(name="groupId") String groupId);

     List<String> getDirectParentGroupIds( @WebParam(name="groupId") String groupId);

     @WebMethod(operationName="getGroupIdsForPrincipal")

     List<String> getGroupIdsForPrincipal( @WebParam(name="principalId") String principalId);

     @WebMethod(operationName="getGroupIdsForPrincipal2")

     List<String> getGroupIdsForPrincipal(

                     @WebParam(name="principalId") String principalId,

                     @WebParam(name="namespaceCode") String namespaceCode

     );

     @WebMethod(operationName="getGroupsForPrincipal")

     List<? extends GroupInfo> getGroupsForPrincipal( @WebParam(name="principalId") String principalId);

     @WebMethod(operationName="getGroupsForPrincipal2")

     List<? extends GroupInfo> getGroupsForPrincipal(

                     @WebParam(name="principalId") String principalId,

                     @WebParam(name="namespaceCode") String namespaceCode

     );

     List<String> getMemberGroupIds( @WebParam(name="groupId") String groupId);

     List<String> getDirectMemberGroupIds( @WebParam(name="groupId") String groupId);

     @WebMethod(operationName="isMemberOfGroup")

         boolean isMemberOfGroup(

                         @WebParam(name="principalId") String principalId,

                         @WebParam(name="groupId") String groupId

         );

     @WebMethod(operationName="isMemberOfGroup2")

         boolean isMemberOfGroup(

                         @WebParam(name="principalId") String principalId,

                         @WebParam(name="namespaceCode") String namespaceCode,

                         @WebParam(name="groupName") String groupName

         );

         boolean isGroupMemberOfGroup(

                         @WebParam(name="potentialMemberGroupId") String potentialMemberGroupId,

                         @WebParam(name="potentialParentId") String potentialParentId

         );

         List<String> getGroupMemberPrincipalIds( @WebParam(name="groupId") String groupId);

         List<String> getDirectGroupMemberPrincipalIds( @WebParam(name="groupId") String groupId);

     boolean addGroupToGroup(

                     @WebParam(name="childId") String childId,

                     @WebParam(name="parentId") String parentId

     );

     boolean removeGroupFromGroup(

                     @WebParam(name="childId") String childId,

                     @WebParam(name="parentId") String parentId

     );

     boolean addPrincipalToGroup(

                     @WebParam(name="principalId") String principalId,

                     @WebParam(name="groupId") String groupId

     );

     boolean removePrincipalFromGroup(

                     @WebParam(name="principalId") String principalId,

                     @WebParam(name="groupId") String groupId

     );

     GroupInfo createGroup( @WebParam(name="groupInfo") GroupInfo groupInfo);

     void removeAllGroupMembers( @WebParam(name="groupId") String groupId);

     GroupInfo updateGroup(

                     @WebParam(name="groupId") String groupId,

                     @WebParam(name="groupInfo") GroupInfo groupInfo

     );

         // *******************************

         // AuthenticationService

         // *******************************

     @WebMethod(exclude=true)

         String getAuthenticatedPrincipalName( @WebParam(name="request") HttpServletRequest request);

         // *******************************

         // AuthorizationService

         // *******************************

     // --------------------

     // Authorization Checks

     // --------------------

     boolean hasPermission(

                     @WebParam(name="principalId") String principalId,

                     @WebParam(name="namespaceCode") String namespaceCode,

                     @WebParam(name="permissionName") String permissionName,

                     @WebParam(name="permissionDetails") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet permissionDetails

     );

     boolean isAuthorized(

                     @WebParam(name="principalId") String principalId,

                     @WebParam(name="namespaceCode") String namespaceCode,

                     @WebParam(name="permissionName") String permissionName,

                     @WebParam(name="permissionDetails") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet permissionDetails,

                     @WebParam(name="qualification") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet qualification

     );

     boolean hasPermissionByTemplateName(

                     @WebParam(name="principalId") String principalId,

                     @WebParam(name="namespaceCode") String namespaceCode,

                     @WebParam(name="permissionTemplateName") String permissionTemplateName,

                     @WebParam(name="permissionDetails") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet permissionDetails

     );

     boolean isAuthorizedByTemplateName(

                     @WebParam(name="principalId") String principalId,

                     @WebParam(name="namespaceCode") String namespaceCode,

                     @WebParam(name="permissionTemplateName") String permissionTemplateName,

                     @WebParam(name="permissionDetails") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet permissionDetails,

                     @WebParam(name="qualification") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet qualification

     );

     /**

      * Returns the matching permission objects for a principal.

      */

     List<? extends KimPermissionInfo> getAuthorizedPermissions(

                     @WebParam(name="principalId") String principalId,

                     @WebParam(name="namespaceCode") String namespaceCode,

                     @WebParam(name="permissionName") String permissionName,

                     @WebParam(name="permissionDetails") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet permissionDetails,

                     @WebParam(name="qualification") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet qualification

     );

     List<? extends KimPermissionInfo> getAuthorizedPermissionsByTemplateName(

                     @WebParam(name="principalId") String principalId,

                     @WebParam(name="namespaceCode") String namespaceCode,

                     @WebParam(name="permissionTemplateName") String permissionTemplateName,

                     @WebParam(name="permissionDetails") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet permissionDetails,

                     @WebParam(name="qualification") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet qualification

     );

     List<PermissionAssigneeInfo> getPermissionAssignees(

                     @WebParam(name="namespaceCode") String namespaceCode,

                     @WebParam(name="permissionName") String permissionName,

                     @WebParam(name="permissionDetails") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet permissionDetails,

                     @WebParam(name="qualification") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet qualification

     );

     List<PermissionAssigneeInfo> getPermissionAssigneesForTemplateName(

                     @WebParam(name="namespaceCode") String namespaceCode,

                     @WebParam(name="permissionTemplateName") String permissionTemplateName,

                     @WebParam(name="permissionDetails") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet permissionDetails,

                     @WebParam(name="qualification") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet qualification

     );

     // ----------------------

     // 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<? extends KimResponsibilityInfo> getResponsibilitiesByName(

                     @WebParam(name="namespaceCode") String namespaceCode,

                     @WebParam(name="responsibilityName") String responsibilityName

     );

     /**

      * 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

     );

     /**

      * Returns true if there are any assigned permissions with the given template.

      */

     boolean isPermissionDefinedForTemplateName(

                     @WebParam(name="namespaceCode") String namespaceCode,

                     @WebParam(name="permissionTemplateName") String permissionTemplateName,

                     @WebParam(name="permissionDetails") @XmlJavaTypeAdapter(value = AttributeSetAdapter.class) AttributeSet permissionDetails

     );

     // ----------------------

     // Cache Flush Methods

     // ----------------------

     void flushAllCaches();

     void flushEntityPrincipalCaches();

         void flushGroupCaches();

         void flushPermissionCaches();

         void flushResponsibilityCaches();

 }