• Home
• dev.fitko.fitconnect.sdk
• client
• 2.3.5
• source code
• FitConnectService.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

dev.fitko.fitconnect.api.FitConnectService Maven / Gradle / Ivy

package dev.fitko.fitconnect.api;

import com.nimbusds.jose.JWEObject;
import com.nimbusds.jose.jwk.RSAKey;
import dev.fitko.fitconnect.api.domain.model.cases.Case;
import dev.fitko.fitconnect.api.domain.model.cases.Cases;
import dev.fitko.fitconnect.api.domain.model.destination.Destination;
import dev.fitko.fitconnect.api.domain.model.event.EventLogEntry;
import dev.fitko.fitconnect.api.domain.model.event.EventPayload;
import dev.fitko.fitconnect.api.domain.model.event.Status;
import dev.fitko.fitconnect.api.domain.model.event.authtags.AuthenticationTags;
import dev.fitko.fitconnect.api.domain.model.event.problems.Problem;
import dev.fitko.fitconnect.api.domain.model.metadata.Metadata;
import dev.fitko.fitconnect.api.domain.model.metadata.attachment.ApiAttachment;
import dev.fitko.fitconnect.api.domain.model.metadata.attachment.AttachmentForValidation;
import dev.fitko.fitconnect.api.domain.model.metadata.data.Data;
import dev.fitko.fitconnect.api.domain.model.reply.AcceptReply;
import dev.fitko.fitconnect.api.domain.model.reply.AnnounceReply;
import dev.fitko.fitconnect.api.domain.model.reply.CreatedReply;
import dev.fitko.fitconnect.api.domain.model.reply.RepliesForPickup;
import dev.fitko.fitconnect.api.domain.model.reply.Reply;
import dev.fitko.fitconnect.api.domain.model.reply.SentReply;
import dev.fitko.fitconnect.api.domain.model.reply.SubmitReply;
import dev.fitko.fitconnect.api.domain.model.submission.AnnounceSubmission;
import dev.fitko.fitconnect.api.domain.model.submission.CreatedSubmission;
import dev.fitko.fitconnect.api.domain.model.submission.SentSubmission;
import dev.fitko.fitconnect.api.domain.model.submission.Submission;
import dev.fitko.fitconnect.api.domain.model.submission.SubmissionForPickup;
import dev.fitko.fitconnect.api.domain.model.submission.SubmissionsForPickup;
import dev.fitko.fitconnect.api.domain.model.submission.SubmitSubmission;
import dev.fitko.fitconnect.api.domain.validation.ValidationResult;
import dev.fitko.fitconnect.api.exceptions.internal.DecryptionException;
import dev.fitko.fitconnect.api.exceptions.internal.EncryptionException;
import dev.fitko.fitconnect.api.exceptions.internal.EventLogException;
import dev.fitko.fitconnect.api.exceptions.internal.RestApiException;

import java.io.InputStream;
import java.net.URI;
import java.util.List;
import java.util.UUID;

/**
 * Service facade to access all basic sdk services used by sender and subscriber.
 */
public interface FitConnectService {

    /**
     * Validates the {@link Metadata} structure against a given JSON-schema to ensure its correctness.
     *
     * @param metadata the {@link Metadata} object that is validated
     * @return a {@link ValidationResult}, contains an error if the {@link Metadata} is invalid or doesn't match the schema
     */
    ValidationResult validateMetadataSchema(Metadata metadata);

    /**
     * Validates the {@link Metadata} structure and contents to ensure its correctness.
     *
     * @param metadata           the {@link Metadata} object that is validated
     * @param submission         the {@link Submission} of the validated metadata
     * @param authenticationTags the {@link AuthenticationTags} of the validated metadata
     * @return a {@link ValidationResult}, contains an error if the {@link Metadata} is invalid, e.g. doesn't match the schema
     */
    ValidationResult validateSubmissionMetadata(Metadata metadata, Submission submission, AuthenticationTags authenticationTags);

    /**
     * Tests if a given string is well-formed JSON syntax.
     *
     * @param jsonData      json byte[] that is tested
     * @param schemaUri URI of schema to validate against
     * @return a {@link ValidationResult} with an optional error
     */
    ValidationResult validateJsonFormat(byte[] jsonData, URI schemaUri);

    /**
     * Tests if a given byte[] is well-formed XML syntax.
     *
     * @param xmlData xml byte[] that is tested
     * @return a {@link ValidationResult} with an optional error
     */
    ValidationResult validateXmlFormat(byte[] xmlData);

    /**
     * Checks if a received callback can be trusted by validating the provided request data
     *
     * @param hmac               authentication code provided by the callback
     * @param timestampInSeconds timestamp in seconds provided by the callback
     * @param httpBody           HTTP body provided by the callback
     * @param callbackSecret     secret owned by the client, which is used to calculate the hmac
     * @return {@code true} if hmac and timestamp provided by the callback meet the required conditions
     */
    ValidationResult validateCallback(String hmac, Long timestampInSeconds, String httpBody, String callbackSecret);

    /**
     * Validates the attachment structure and contents to ensure its correctness.
     *
     * @param attachmentsForValidation list of attachments containing the hash, decrypted and encrypted data needed for validation
     * @param authenticationTags       the {@link AuthenticationTags} of the validated attachments
     * @return a {@link ValidationResult}, contains an error if the attachment is invalid
     */
    ValidationResult validateAttachments(List attachmentsForValidation, AuthenticationTags authenticationTags);

    ValidationResult validateReplyMetadata(Metadata metadata, Reply reply, AuthenticationTags authenticationTags);

    /**
     * Validates the {@link Data} structure and contents to ensure its correctness.
     *
     * @param data               the unencrypted data as byte[]
     * @param encryptedData      the encrypted data of the {@link Submission}
     * @param metadata           the {@link Metadata} of the validated data
     * @param authenticationTags the authenticationTags of the validated data
     * @return a {@link ValidationResult}, contains an error if the {@link Metadata} is invalid, e.g. doesn't match the schema
     */
    ValidationResult validateData(byte[] data, String encryptedData, Metadata metadata, String authenticationTags);

    /**
     * Encrypts the submission data payload (json or xml) with JWE (JSON-Web-Encryption).
     *
     * @param publicKey   the public encryption key for encryption of {@link Data}
     * @param data        the {@link Data} payload that should be encrypted
     * @param contentType MIME content type of the object to encrypt
     * @return the JWE-encrypted {@link Data}
     * @throws EncryptionException if the encryption fails due to an invalid key or corrupt data
     */
    String encryptBytes(RSAKey publicKey, byte[] data, String contentType) throws EncryptionException;

    JWEObject encryptInputStream(RSAKey publicKey, InputStream inputStream, String contentType) throws EncryptionException;

    /**
     * Encrypts an object with JWE (JSON-Web-Encryption).
     *
     * @param publicKey   the public encryption key
     * @param object      the data payload that should be encrypted
     * @param contentType MIME content type of the object to encrypt
     * @return the JWE-encrypted {@link Data}
     * @throws EncryptionException if the encryption fails due to an invalid key or corrupt data
     */
    String encryptObject(RSAKey publicKey, Object object, String contentType) throws EncryptionException;

    /**
     * Decrypts JWE-encrypted string data.
     *
     * @param privateKey       the private key to decrypt the JWE-encrypted string
     * @param encryptedContent JWE encrypted content that should be decrypted
     * @return the decrypted content as byte[]
     */
    byte[] decryptString(RSAKey privateKey, String encryptedContent) throws DecryptionException;

    /**
     * Create message digest (SHA-512) of a given byte[]
     *
     * @param data input bytes that should be hashed
     * @return hex-string representation of hashed byte[]
     */
    String createHash(byte[] data);

    String createHash(InputStream inputStream);

    /**
     * Polls available {@link SubmissionForPickup}s for a given destinationId.
     *
     * @param destinationId restricts the query to a specific destination
     * @param limit         number of submissions in result (max. is 500)
     * @param offset        position in the dataset
     * @return list of found {@link SubmissionForPickup}s
     */
    SubmissionsForPickup getAvailableSubmissions(UUID destinationId, int offset, int limit) throws RestApiException;

    /**
     * Creates and announces a new {@link AnnounceSubmission}.
     *
     * @param submission with a destinationId, a list of attachmentIds and a serviceType
     * @return the announced submission
     */
    CreatedSubmission announceSubmission(AnnounceSubmission submission);

    /**
     * Send a {@link SubmitSubmission} that includes encrypted {@link Metadata} and {@link Data}
     *
     * @param submission submission to submit
     * @return sent {@link Submission}
     */
    Submission sendSubmission(SubmitSubmission submission);

    /**
     * Uploads encrypted {@link ApiAttachment}s to for given submission id.
     *
     * @param submissionId        unique identifier of the  submission
     * @param attachmentId        unique identifier of the attachment
     * @param encryptedAttachment string of JWE encrypted attachment
     */
    void uploadSubmissionAttachment(UUID submissionId, UUID attachmentId, String encryptedAttachment);

    /**
     * Gets a {@link Submission}.
     *
     * @param submissionId the unique identifier of a {@link Submission}
     * @return the requested {@link Submission}
     */
    Submission getSubmission(UUID submissionId) throws RestApiException;

    void uploadSubmissionAttachmentStream(UUID submissionId, UUID attachmentId, InputStream encryptedAttachment) throws RestApiException;

    /**
     * Loads encrypted {@link ApiAttachment} for a {@link Submission}.
     *
     * @param submissionId the unique identifier of a {@link Submission}
     * @param attachmentId unique identifier of the attachments
     * @return encrypted JWE string of attachment
     */
    String getSubmissionAttachment(UUID submissionId, UUID attachmentId) throws RestApiException;

    /**
     * Sends a confirmation event if the received submission matches all validations.
     *
     * @param eventPayload contains submissionId, caseId, destination and a list of problems
     * @see Process And Acknowledge
     */
    void acceptSubmission(EventPayload eventPayload) throws RestApiException;

    /**
     * Sends a rejection event if the received submission violates any validation rule.
     *
     * @param eventPayload contains submissionId, caseId, destination and a list of problems
     * @see Process And Acknowledge
     */
    void rejectSubmission(EventPayload eventPayload) throws RestApiException;

    /**
     * Gets {@link Destination} by id.
     *
     * @param destinationId unique identifier of a {@link Destination}
     * @return the destination
     */
    Destination getDestination(UUID destinationId);

    /**
     * Retrieves the public encryption key for a destination.
     *
     * @param destinationId unique identifier of the destination
     * @return the public key for encrypting {@link Metadata}, {@link Data} and {@link ApiAttachment}s
     */
    RSAKey getEncryptionKeyForDestination(UUID destinationId);

    /**
     * Retrieves the public encryption key for a destination.
     *
     * @param destination the destination the public key is retrieved for
     * @return the public key for encrypting {@link Metadata}, {@link Data} and {@link ApiAttachment}s
     */
    RSAKey getEncryptionKeyForDestination(Destination destination);

    /**
     * Retrieve the entire event log for a submissions caseId of a specific destination.
     *
     * @param caseId        unique identifier of the case the log should be retrieved for
     * @param destinationId unique identifier of the {@link Destination} the log should be retrieved for
     * @return List of {@link EventLogEntry}s for the given case
     */
    List getEventLog(UUID caseId, UUID destinationId);

    /**
     * Retrieve the current status of a {@link Submission}.
     *
     * @param sentSubmission sent submission including authentication tags
     * @return {@link Status} the current status
     */
    Status getStatus(SentSubmission sentSubmission) throws RestApiException;

    /**
     * Retrieve the current status of a {@link Reply}.
     *
     * @param reply sent reply including authentication tags
     * @return {@link Status} the current reply status
     */
    Status getStatus(SentReply reply) throws RestApiException;

    /**
     * Get event from event-log filtered by a given event and submission.
     *
     * @param submission submission to filter the event-log by
     * @return {@link AuthenticationTags} of metadata, data and attachments
     */
    AuthenticationTags getSubmissionAuthenticationTags(Submission submission) throws RestApiException;

    /**
     * Get event from event-log filtered by a given event and reply.
     *
     * @param reply reply to filter the event-log by
     * @return {@link AuthenticationTags} of metadata, data and attachments
     */
    AuthenticationTags getReplyAuthenticationTags(Reply reply) throws RestApiException, EventLogException;

    Cases listCases(int limit, int offset) throws RestApiException, EventLogException;

    Case getCase(UUID caseId) throws RestApiException, EventLogException;

    Reply getReply(UUID replyId) throws RestApiException;

    RepliesForPickup getAvailableReplies(int limit, int offset) throws RestApiException;

    void uploadReplyAttachment(UUID replyId, UUID attachmentId, String encryptedAttachment) throws RestApiException;

    String getReplyAttachment(UUID replyId, UUID attachmentId) throws RestApiException;

    SentReply submitReply(UUID replyId, SubmitReply submitReply) throws RestApiException;

    CreatedReply announceReply(AnnounceReply announceReply) throws RestApiException;

    String acceptReply(UUID replyId, AcceptReply acceptReply) throws RestApiException;

    String rejectReply(UUID replyId, List problems) throws RestApiException;

    Status getSubmitState(Submission submission);
}