com.rogiel.httpchannel.service.UploadService Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of httpchannel-api Show documentation

Module that defines the HttpChannel API. HttpChannels abstract complex download and upload steps into a simple and easy to use NIO Channel. NIO Channels can be wrapped into an InputStream or OutputStream and used in any way you may find possible to. Aside from that, Channels can be used natively in most next-gen libraries, meaning that you don't even need to wrap anything, just start writing or reading data to or from the channel wth a ByteBuffer. Anyone using the library should try to rely on code from this module only and, only if necessary, on configuration classes that are implementation specific. Relying on any other resource or class is considered an error and should NOT be done. One of the most interesting usages of channels for uploads and download is that you can easily copy data straight from one channel to the other, with less than 10 lines of code! Also, channels allows the implementation of a "tee" mechanism, in which data redden from a single channel can be copied to several other channels on the fly!

The newest version!

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you 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.rogiel.httpchannel.service;

import com.rogiel.httpchannel.service.Uploader.UploaderConfiguration;
import com.rogiel.httpchannel.service.config.NullUploaderConfiguration;

/**
 * Implements an service capable of uploading a file.
 * 
 * @author Rogiel
 * @since 1.0
 */
public interface UploadService extends Service {
	/**
	 * Creates a new instance of {@link Uploader}. This instance is attached
	 * with the parent {@link Service} instance.

	 * Note: not all services might support description
	 * 
	 * @param filename
	 *            the name of the file to be uploaded
	 * @param filesize
	 *            the size of the file to be uploaded. This must be exact.
	 * @param configuration
	 *            the uploader configuration
	 * @return the new {@link Uploader} instance
	 */
	Uploader getUploader(String filename, long filesize, C configuration);

	/**
	 * Creates a new instance of {@link Uploader}. This instance is attached
	 * with the parent {@link Service} instance.

	 * Note: not all services might support description
	 * 
	 * @param filename
	 *            the name of the file to be uploaded
	 * @param filesize
	 *            the size of the file to be uploaded. This must be exact.
	 * @return the new {@link Uploader} instance
	 */
	Uploader getUploader(String filename, long filesize);

	/**
	 * Creates a new configuration object. If a service does not support or
	 * require configuration, {@link NullUploaderConfiguration} should be
	 * returned.
	 * 
	 * @return a new configuration object or {@link NullUploaderConfiguration}
	 */
	C newUploaderConfiguration();

	/**
	 * Get the maximum upload file size supported by this service.
	 * 
	 * Please note that the value returned by this method may vary based
	 * on it's state (i.e. premium or not).
	 * 
	 * @return the maximum filesize supported
	 */
	long getMaximumFilesize();

	/**
	 * Get the list of all supported extensions. Might return null if
	 * there is no restriction.
	 * 
	 * Please note that the value returned by this method may vary based
	 * on it's state (i.e. premium or not).
	 * 
	 * @return the list of supported file extensions. Can return null
	 *         if there is not restriction
	 */
	String[] getSupportedExtensions();

	/**
	 * Return the matrix of capabilities for this {@link Uploader}.
	 * 
	 * @return {@link CapabilityMatrix} with all capabilities of this
	 *         {@link Uploader}.
	 * @see UploaderCapability
	 */
	CapabilityMatrix getUploadCapabilities();
}