com.rogiel.httpchannel.service.Uploader 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 java.io.IOException;

import com.rogiel.httpchannel.captcha.CaptchaService;
import com.rogiel.httpchannel.captcha.exception.UnsolvableCaptchaServiceException;
import com.rogiel.httpchannel.service.Uploader.UploaderConfiguration;
import com.rogiel.httpchannel.service.exception.NoCaptchaServiceException;

/**
 * This interfaces provides uploading for an service.
 * 
 * @author Rogiel
 * @since 1.0
 */
public interface Uploader {
	/**
	 * Opens a new {@link UploadChannel} that will be immediately ready to
	 * receive data to be sent to the upload stream.
	 * 
	 * Whether an channel is returned or any exception is thrown it is NOT possible to reuse the same instance for
	 * more than one upload!
	 * 

	 * Please remember to close the channel before calling
	 * {@link UploadChannel#getDownloadLink()} or aborting the upload. The
	 * {@link UploadChannel#close()} method will finish upload (may take some
	 * time) and release any of the resources (such as network connections and
	 * file handlers) that could continue open for the whole runtime or until
	 * they time out, which could never occur. Note that you should close the
	 * channel even when an exception is thrown.
	 * 
	 * @return the {@link UploadChannel} instance
	 * @throws IOException
	 *             if any IO error occur
	 * @throws UnsolvableCaptchaServiceException
	 *             if the service required captcha resolving but no
	 *             {@link CaptchaService} was available or the service did not
	 *             solve the challenge
	 * @throws NoCaptchaServiceException
	 *             if the service required an {@link CaptchaService}
	 *             implementation to be present, but none was available
	 */
	UploadChannel openChannel() throws IOException,
			UnsolvableCaptchaServiceException, NoCaptchaServiceException;

	/**
	 * Returns this {@link Uploader} configuration.
	 * 
	 * IMPORTANT NOTE: You should not modify any configuration within
	 * this configuration object once the upload has started. Doing so, could
	 * result in a error.
	 * 
	 * @return this {@link Uploader} configuration
	 */
	C getConfiguration();

	/**
	 * This interface must be implemented in order to allow upload
	 * configuration.
	 * 
	 * @author Rogiel
	 */
	public interface UploaderConfiguration {
		/**
		 * Checks whether the configuration object can be casted to
		 * type
		 * 
		 * @param type
		 *            the casting type
		 * @return true if this object can be casted to
		 *         type
		 */
		boolean is(Class type);

		/**
		 * Casts this object to type. If cannot be casted,
		 * null is returned.
		 * 
		 * @param type
		 *            the casting type
		 * @return the casted configuration
		 */
		 T as(Class type);
	}

	/**
	 * Defines an {@link UploaderConfiguration} that can allow at least
	 * an description field
	 * 
	 * @author Rogiel
	 */
	public interface DescriptionableUploaderConfiguration extends
			UploaderConfiguration {
		public static final String DEFAULT_DESCRIPTION = "Uploaded by httpchannel";

		/**
		 * @return the upload description
		 */
		String description();

		/**
		 * @param description
		 *            the upload description
		 */
		DescriptionableUploaderConfiguration description(String description);
	}
}