com.rogiel.httpchannel.service.UploadChannel 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 java.net.URI;
import java.nio.channels.Channel;
import java.nio.channels.WritableByteChannel;

import com.rogiel.httpchannel.service.exception.UploadLinkNotFoundException;

/**
 * This is an {@link Channel} for uploads. Any data to be uploaded, must be
 * written into this channel.
 * 
 * Since this {@link Channel} implements {@link WritableByteChannel}
 * you can treat it as any other regular IO {@link Channel}.
 * 
 * Remember: always close the {@link Channel}, if you do otherwise, your
 * upload will not finish and will never return the link.
 * 
 * @author Rogiel
 */
public interface UploadChannel extends HttpChannel, WritableByteChannel {
	/**
	 * The link is located after you call {@link UploadChannel#close()}, but it
	 * can only be retrieved by calling this method. If {@link #close()} throwed
	 * an exception, this method might return null.
	 * 
	 * @return the download link for this upload
	 */
	URI getDownloadLink();

	/**
	 * @return the service instance providing this upload
	 */
	@Override
	UploadService getService();

	/**
	 * @return the {@link Uploader} providing this upload
	 */
	Uploader getUploader();

	/**
	 * @throws UploadLinkNotFoundException
	 *             if after the upload, the download link cannot be found
	 */
	@Override
	void close() throws IOException, UploadLinkNotFoundException;
}