com.rogiel.httpchannel.service.Authenticator 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.Authenticator.AuthenticatorConfiguration;
import com.rogiel.httpchannel.service.exception.AuthenticationInvalidCredentialException;
import com.rogiel.httpchannel.service.exception.NoCaptchaServiceException;

/**
 * This interfaces provides authentication for an service.
 * 
 * @author Rogiel
 * @since 1.0
 */
public interface Authenticator {
	/**
	 * Login into the {@link Service}. Once the authentication is done, it is
	 * persistent for the entire service's operation.

	 * Note: If you want to logout the user, see
	 * {@link Authenticator#logout()}
	 * 
	 * @throws IOException
	 *             if any IO error occur
	 * @throws AuthenticationInvalidCredentialException
	 *             if the credentials are not valid or cannot be used
	 * @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
	 */
	void login() throws IOException, AuthenticationInvalidCredentialException,
			UnsolvableCaptchaServiceException, NoCaptchaServiceException;

	/**
	 * Logout into the {@link Service}. The session is restored to an not
	 * logged-in state.
	 * 
	 * @throws IOException
	 *             if any IO error occur
	 */
	void logout() throws IOException;

	/**
	 * Returns this {@link Authenticator} configuration.
	 * 
	 * IMPORTANT NOTE: You should not modify any configuration within
	 * this configuration object once while the account is authenticated.
	 * Depending on the service, changing any setting could result in an state
	 * where the service cannot be logged out.
	 * 
	 * @return this {@link Authenticator} configuration
	 */
	C getConfiguration();

	/**
	 * This interface must be implemented in order to allow authentication
	 * configuration.
	 * 
	 * @author Rogiel
	 */
	public interface AuthenticatorConfiguration {
		/**
		 * 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);
	}
}