1 /*
2 * Copyright 2012-2025 CodeLibs Project and the Others.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
13 * either express or implied. See the License for the specific language
14 * governing permissions and limitations under the License.
15 */
16 package org.codelibs.fess.storage;
17
18 import java.io.InputStream;
19 import java.io.OutputStream;
20 import java.util.List;
21 import java.util.Map;
22
23 /**
24 * Interface for cloud storage operations.
25 * Implementations provide access to S3-compatible storage, GCS, or other cloud storage systems.
26 */
27 public interface StorageClient extends AutoCloseable {
28
29 /**
30 * Uploads an object to storage.
31 *
32 * @param objectName the name/path for the object
33 * @param inputStream the input stream of data to upload
34 * @param size the size of the data in bytes
35 * @param contentType the MIME type of the content
36 */
37 void uploadObject(String objectName, InputStream inputStream, long size, String contentType);
38
39 /**
40 * Downloads an object from storage.
41 *
42 * @param objectName the name/path of the object to download
43 * @param outputStream the output stream to write data to
44 */
45 void downloadObject(String objectName, OutputStream outputStream);
46
47 /**
48 * Deletes an object from storage.
49 *
50 * @param objectName the name/path of the object to delete
51 */
52 void deleteObject(String objectName);
53
54 /**
55 * Lists objects in storage with the given prefix.
56 *
57 * @param prefix the path prefix to list objects under (null or empty for root)
58 * @param maxItems maximum number of items to return
59 * @return list of storage items
60 */
61 List<StorageItem> listObjects(String prefix, int maxItems);
62
63 /**
64 * Gets tags/metadata for an object.
65 *
66 * @param objectName the name/path of the object
67 * @return map of tag key-value pairs
68 */
69 Map<String, String> getObjectTags(String objectName);
70
71 /**
72 * Sets tags/metadata for an object.
73 *
74 * @param objectName the name/path of the object
75 * @param tags the tags to set
76 */
77 void setObjectTags(String objectName, Map<String, String> tags);
78
79 /**
80 * Ensures the bucket exists, creating it if necessary.
81 */
82 void ensureBucketExists();
83
84 /**
85 * Checks if storage is properly configured and accessible.
86 *
87 * @return true if storage is available
88 */
89 boolean isAvailable();
90
91 /**
92 * Closes the client and releases resources.
93 */
94 @Override
95 void close();
96 }