1 /*
2 Licensed under the Apache License, Version 2.0 (the "License");
3 you may not use this file except in compliance with the License.
4 You may obtain a copy of the License at
5
6 http://www.apache.org/licenses/LICENSE-2.0
7
8 Unless required by applicable law or agreed to in writing, software
9 distributed under the License is distributed on an "AS IS" BASIS,
10 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
11 See the License for the specific language governing permissions and
12 limitations under the License.
13 */
14 package uk.nhs.interoperability.capabilities;
15
16 import com.xmlsolutions.annotation.Requirement;
17
18 import uk.nhs.interoperability.infrastructure.ITKMessageProperties;
19
20 /**
21 * An representation of an ITK compliant* audit service that has the capability
22 * to audit ITK messaging related events
23 *
24 * In general the expected usage pattern is to audit on both the client and service
25 * provider sides of any ITK operation. Additionally the intent to do something
26 * should be audited - e.g. intention to send a message or call a service {@link #MESSAGE_SENT_EVENT}.
27 * An additional audit call may then be required for the same logical action should
28 * any processing errors occur - e.g. connection timeouts {@link #MESSAGE_PROCESSING_FAILURE}
29 *
30 * <br/><br/>
31 * *TODO note further work is required to understand the audit requirements
32 * around the human actors (patient and carer) in the audit
33 *
34 * @author Michael Odling-Smee
35 * @author Nicholas Jones
36 * @since version 0.1
37 */
38 public interface AuditService {
39
40 /**
41 * Constant representing the receipt of an ITK message
42 */
43 public static final String MESSAGE_RECEIPT_EVENT = "Message received";
44
45 /**
46 * Constant representing the sending of an ITK message
47 */
48 public static final String MESSAGE_SENT_EVENT = "Message sent";
49
50 /**
51 * Constant representing the event of message processing failure
52 */
53 public static final String MESSAGE_PROCESSING_FAILURE = "Message processing failed";
54
55 /**
56 * Writes an audit event to the audit service using the supplied information.
57 * @param event The string description of the event - e.g.
58 * {@link #MESSAGE_PROCESSING_FAILURE}, {@link #MESSAGE_RECEIPT_EVENT}, {@link #MESSAGE_SENT_EVENT}
59 * @param eventTime The time the event occurred (in unix time). Note depending on the implementation this
60 * may differ from the time at which the audit record is actually committed
61 * @param itkMessageProperties The properties of the message to which this event pertains
62 * @throws AuditException If there are any issues accessing the underlying audit implementation
63 * (e.g. I/O exception) or if the <code>event</code> and/or <code>itkMessageProperties</code> is <code>null</code>
64 */
65 @Requirement(traceTo="IFA-SEC-02", status="abstract")
66 public void auditEvent(String event, long eventTime, ITKMessageProperties itkMessageProperties) throws AuditException;
67
68 }