001package ca.uhn.fhir.jpa.binary.api;
002
003/*-
004 * #%L
005 * HAPI FHIR Storage api
006 * %%
007 * Copyright (C) 2014 - 2022 Smile CDR, Inc.
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 org.hl7.fhir.instance.model.api.IBaseBinary;
024import org.hl7.fhir.instance.model.api.IIdType;
025
026import javax.annotation.Nonnull;
027import java.io.IOException;
028import java.io.InputStream;
029import java.io.OutputStream;
030
031public interface IBinaryStorageSvc {
032
033        /**
034         * Gets the maximum number of bytes that can be stored in a single binary
035         * file by this service. The default is {@link Integer#MAX_VALUE}
036         */
037        int getMaximumBinarySize();
038
039        /**
040         * Sets the maximum number of bytes that can be stored in a single binary
041         * file by this service. The default is {@link Integer#MAX_VALUE}
042         *
043         * @param theMaximumBinarySize The maximum size
044         */
045        void setMaximumBinarySize(int theMaximumBinarySize);
046
047        /**
048         * Gets the minimum number of bytes that will be stored. Binary content smaller
049         * * than this threshold may be inlined even if a binary storage service
050         * * is active.
051         */
052        int getMinimumBinarySize();
053
054        /**
055         * Sets the minimum number of bytes that will be stored. Binary content smaller
056         * than this threshold may be inlined even if a binary storage service
057         * is active.
058         */
059        void setMinimumBinarySize(int theMinimumBinarySize);
060
061        /**
062         * Give the storage service the ability to veto items from storage
063         *
064         * @param theSize        How large is the item
065         * @param theResourceId  What is the resource ID it will be associated with
066         * @param theContentType What is the content type
067         * @return <code>true</code> if the storage service should store the item
068         */
069        boolean shouldStoreBlob(long theSize, IIdType theResourceId, String theContentType);
070
071        /**
072         * Generate a new blob ID that will be passed to {@link #storeBlob(IIdType, String, String, InputStream)} later
073         */
074        String newBlobId();
075
076        /**
077         * Store a new binary blob
078         *
079         * @param theResourceId   The resource ID that owns this blob. Note that it should not be possible to retrieve a blob without both the resource ID and the blob ID being correct.
080         * @param theBlobIdOrNull If set, forces
081         * @param theContentType  The content type to associate with this blob
082         * @param theInputStream  An InputStream to read from. This method should close the stream when it has been fully consumed.
083         * @return Returns details about the stored data
084         */
085        @Nonnull
086        StoredDetails storeBlob(IIdType theResourceId, String theBlobIdOrNull, String theContentType, InputStream theInputStream) throws IOException;
087
088        StoredDetails fetchBlobDetails(IIdType theResourceId, String theBlobId) throws IOException;
089
090        /**
091         * @return Returns <code>true</code> if the blob was found and written, of <code>false</code> if the blob was not found (i.e. it was expunged or the ID was invalid)
092         */
093        boolean writeBlob(IIdType theResourceId, String theBlobId, OutputStream theOutputStream) throws IOException;
094
095        void expungeBlob(IIdType theResourceId, String theBlobId);
096
097        /**
098         * Fetch the contents of the given blob
099         *
100         * @param theResourceId The resource ID
101         * @param theBlobId     The blob ID
102         * @return The payload as a byte array
103         */
104        byte[] fetchBlob(IIdType theResourceId, String theBlobId) throws IOException;
105
106        /**
107         * Fetch the byte[] contents of a given Binary resource's `data` element. If the data is a standard base64encoded string that is embedded, return it.
108         * Otherwise, attempt to load the externalized binary blob via the the externalized binary storage service.
109         *
110         * @param theResourceId The resource ID The ID of the Binary resource you want to extract data bytes from
111         * @return The binary data blob as a byte array
112         */
113        byte[] fetchDataBlobFromBinary(IBaseBinary theResource) throws IOException;
114}