001package ca.uhn.fhir.rest.server.interceptor.consent; 002 003/*- 004 * #%L 005 * HAPI FHIR - Server Framework 006 * %% 007 * Copyright (C) 2014 - 2019 University Health Network 008 * %% 009 * Licensed under the Apache License, Version 2.0 (the "License"); 010 * you may not use this file except in compliance with the License. 011 * You may obtain a copy of the License at 012 * 013 * http://www.apache.org/licenses/LICENSE-2.0 014 * 015 * Unless required by applicable law or agreed to in writing, software 016 * distributed under the License is distributed on an "AS IS" BASIS, 017 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 018 * See the License for the specific language governing permissions and 019 * limitations under the License. 020 * #L% 021 */ 022 023import ca.uhn.fhir.rest.api.server.RequestDetails; 024import ca.uhn.fhir.rest.server.exceptions.BaseServerResponseException; 025import org.hl7.fhir.instance.model.api.IBaseResource; 026 027public interface IConsentService { 028 029 /** 030 * This method is called when an operation is initially beginning, before any 031 * significant processing occurs. The service may use this method to decide 032 * whether the request needs to be reviewed further or not. 033 * 034 * @param theRequestDetails Contains details about the operation that is 035 * beginning, including details about the request type, 036 * URL, etc. Note that the RequestDetails has a generic 037 * Map (see {@link RequestDetails#getUserData()}) that 038 * can be used to store information and state to be 039 * passed between methods in the consent service. 040 * @param theContextServices An object passed in by the consent framework that 041 * provides utility functions relevant to acting on 042 * consent directives. 043 * @return An outcome object. See {@link ConsentOutcome} 044 */ 045 ConsentOutcome startOperation(RequestDetails theRequestDetails, IConsentContextServices theContextServices); 046 047 /** 048 * This method is called if a user may potentially see a resource via READ 049 * operations, SEARCH operations, etc. This method may make decisions about 050 * whether or not the user should be permitted to see the resource. 051 * <p> 052 * Implementations should make no attempt to modify the returned result within 053 * this method. For modification use cases (e.g. masking for consent rules) the 054 * user should use the {@link #willSeeResource(RequestDetails, IBaseResource, IConsentContextServices)} 055 * method to actually make changes. This method is intended to only 056 * to make decisions. 057 * </p> 058 * <b>Performance note:</b> Note that this method should be efficient, since it will be called once 059 * for every resource potentially returned (e.g. by searches). If this method 060 * takes a significant amount of time to execute, performance on the server 061 * will suffer. 062 * </p> 063 * 064 * @param theRequestDetails Contains details about the operation that is 065 * beginning, including details about the request type, 066 * URL, etc. Note that the RequestDetails has a generic 067 * Map (see {@link RequestDetails#getUserData()}) that 068 * can be used to store information and state to be 069 * passed between methods in the consent service. 070 * @param theResource The resource that will be exposed 071 * @param theContextServices An object passed in by the consent framework that 072 * provides utility functions relevant to acting on 073 * consent directives. 074 * @return An outcome object. See {@link ConsentOutcome} 075 */ 076 ConsentOutcome canSeeResource(RequestDetails theRequestDetails, IBaseResource theResource, IConsentContextServices theContextServices); 077 078 /** 079 * This method is called if a user is about to see a resource, either completely 080 * or partially. In other words, if the user is going to see any part of this resource 081 * via READ operations, SEARCH operations, etc., this method is 082 * called. This method may modify the resource in order to filter/mask aspects of 083 * the contents, or even to enrich it. 084 * <p> 085 * The returning {@link ConsentOutcome} may optionally replace the resource 086 * with a different resource (including an OperationOutcome) by calling the 087 * resource property on the {@link ConsentOutcome}. 088 * </p> 089 * <p> 090 * In addition, the {@link ConsentOutcome} must return one of the following 091 * statuses: 092 * </p> 093 * <ul> 094 * <li>{@link ConsentOperationStatusEnum#AUTHORIZED}: The resource will be returned to the client.</li> 095 * <li>{@link ConsentOperationStatusEnum#PROCEED}: The resource will be returned to the client. Any embedded resources contained within the resource will also be checked by {@link #willSeeResource(RequestDetails, IBaseResource, IConsentContextServices)}.</li> 096 * <li>{@link ConsentOperationStatusEnum#REJECT}: The resource will not be returned to the client. If the resource supplied to the </li> 097 * </ul> 098 * 099 * @param theRequestDetails Contains details about the operation that is 100 * beginning, including details about the request type, 101 * URL, etc. Note that the RequestDetails has a generic 102 * Map (see {@link RequestDetails#getUserData()}) that 103 * can be used to store information and state to be 104 * passed between methods in the consent service. 105 * @param theResource The resource that will be exposed 106 * @param theContextServices An object passed in by the consent framework that 107 * provides utility functions relevant to acting on 108 * consent directives. 109 * @return An outcome object. See method documentation for a description. 110 */ 111 ConsentOutcome willSeeResource(RequestDetails theRequestDetails, IBaseResource theResource, IConsentContextServices theContextServices); 112 113 /** 114 * This method is called when an operation is complete. It can be used to perform 115 * any necessary cleanup, flush audit events, etc. 116 * <p> 117 * This method is not called if the request failed. {@link #completeOperationFailure(RequestDetails, BaseServerResponseException, IConsentContextServices)} 118 * will be called instead in that case. 119 * </p> 120 * 121 * @param theRequestDetails Contains details about the operation that is 122 * beginning, including details about the request type, 123 * URL, etc. Note that the RequestDetails has a generic 124 * Map (see {@link RequestDetails#getUserData()}) that 125 * can be used to store information and state to be 126 * passed between methods in the consent service. 127 * @param theContextServices An object passed in by the consent framework that 128 * provides utility functions relevant to acting on 129 * consent directives. 130 * @see #completeOperationFailure(RequestDetails, BaseServerResponseException, IConsentContextServices) 131 */ 132 void completeOperationSuccess(RequestDetails theRequestDetails, IConsentContextServices theContextServices); 133 134 /** 135 * This method is called when an operation is complete. It can be used to perform 136 * any necessary cleanup, flush audit events, etc. 137 * <p> 138 * This method will be called if the request did not complete successfully, instead of 139 * {@link #completeOperationSuccess(RequestDetails, IConsentContextServices)}. Typically this means that 140 * the operation failed and a failure is being returned to the client. 141 * </p> 142 * 143 * @param theRequestDetails Contains details about the operation that is 144 * beginning, including details about the request type, 145 * URL, etc. Note that the RequestDetails has a generic 146 * Map (see {@link RequestDetails#getUserData()}) that 147 * can be used to store information and state to be 148 * passed between methods in the consent service. 149 * @param theContextServices An object passed in by the consent framework that 150 * provides utility functions relevant to acting on 151 * consent directives. 152 * @see #completeOperationSuccess(RequestDetails, IConsentContextServices) 153 */ 154 void completeOperationFailure(RequestDetails theRequestDetails, BaseServerResponseException theException, IConsentContextServices theContextServices); 155}