com.eimapi.fileserver.FileService Maven / Gradle / Ivy
/*
* Copyright 2017 eimapi.com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.eimapi.fileserver;
import com.eimapi.fileserver.exception.FileServerException;
import com.eimapi.fileserver.model.FileDescriptor;
import java.io.InputStream;
import java.util.Map;
/**
* File server interface to define all basic methods to create, update,
* delete and load file at repository.
*
* @author Denys G. Santos
* @version 0.0.1
* @since 0.0.1
*/
public interface FileService {
/**
* Create a new file at repository. As response this method will return an extension of
* {@link FileDescriptor}, that contain all properties to manage file at each kind of
* repository implementation.
*
* When using this method the file mimetype and encode will not be defined.
*
* If you want to:
*
* -
* Define mimetype and encode, you should use the
* {@link FileService#create(InputStream, String, String)} method
*
* -
* Calculate automatically the mymetype and encode, you should use
* {@link FileService#create(InputStream, boolean, boolean)} method
*
*
*
* @param inputStream the stream to be stored at repository
* @param the {@link FileDescriptor} extension
* @return E the {@link FileDescriptor}
* @throws FileServerException if any exception occurs
*/
E create(InputStream inputStream) throws FileServerException;
/**
* Create a new file at repository. As response this method will return an extension of
* {@link FileDescriptor}, that contain all properties to manage file at each kind of
* repository implementation.
*
* @param inputStream the stream to be stored at repository
* @param properties some properties extras properties.
* @param the {@link FileDescriptor} extension
* @return E the {@link FileDescriptor}
* @throws FileServerException if any exception occurs
*/
E create(InputStream inputStream, final Map properties)
throws FileServerException;
/**
* Create a new file at repository. As response this method will return an extension of
* {@link FileDescriptor}, that contain all properties to manage file at each kind of
* repository implementation.
*
* Instead use create(outputStream, false, false), is recommended use
* {@link FileService#create(InputStream)} method.
*
* @param inputStream the stream to be stored at repository
* @param discoveryMimetype if true the system will calculate the mimetype based on stream
* @param discoveryEncode if true the system will calculate the encode based on stream
* @param the {@link FileDescriptor} extension
* @return E the {@link FileDescriptor}
* @throws FileServerException if any exception occurs
*/
E create(InputStream inputStream, boolean discoveryMimetype,
boolean discoveryEncode) throws FileServerException;
/**
* Create a new file at repository. As response this method will return an extension of
* {@link FileDescriptor}, that contain all properties to manage file at each kind of
* repository implementation.
*
* Instead use create(outputStream, null, null), is recommended use
* {@link FileService#create(InputStream)} method.
*
* @param inputStream the stream to be stored at repository
* @param mimetype the file mimetype.
* @param encode te file encode.
* @param the {@link FileDescriptor} extension
* @return E the {@link FileDescriptor}
* @throws FileServerException if any exception occurs
*/
E create(InputStream inputStream, String mimetype, String encode)
throws FileServerException;
/**
* Update the existent file. As response this method will return an extension of
* {@link FileDescriptor}, that contain all properties to manage file at each kind of
* repository implementation.
*
* @param inputStream the stream to be stored at repository
* @param properties some properties extras properties that will overwrite originals.
* @param the {@link FileDescriptor} extension
* @return E the {@link FileDescriptor}
* @throws FileServerException if any exception occurs
*/
E update(InputStream inputStream, final Map properties) throws FileServerException;
/**
* Update the existent file. As response this method will return an extension of
* {@link FileDescriptor}, that contain all properties to manage file at each kind of
* repository implementation.
*
* @param inputStream the stream to be stored at repository
* @param fileDescriptor the file descriptor that define what file will be overwritten
* @param the {@link FileDescriptor} extension
* @return E the {@link FileDescriptor}
* @throws FileServerException if any exception occurs
*/
E update(InputStream inputStream, final E fileDescriptor) throws FileServerException;
/**
* Delete file described by {@link FileDescriptor} from repository.
*
* @param fileDescriptor the file descriptor that define what file will be deleted
* @param the {@link FileDescriptor} extension
* @throws FileServerException if any exception occurs
*/
void delete(final E fileDescriptor) throws FileServerException;
/**
* Load an {@link InputStream} from a file stored in repository. This operation use the information
* form {@link FileDescriptor} to load a stream
*
* @param fileDescriptor the file descriptor that define what file will be load
* @param the {@link FileDescriptor} extension
* @return InputStream the file input stream
* @throws FileServerException if any exception occurs
*/
InputStream getStream(final E fileDescriptor) throws FileServerException;
}