1 /*
2 * #%L
3 * Authenticator.java - mongodb-async-driver - Allanbank Consulting, Inc.
4 * %%
5 * Copyright (C) 2011 - 2014 Allanbank Consulting, Inc.
6 * %%
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
10 *
11 * http://www.apache.org/licenses/LICENSE-2.0
12 *
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
18 * #L%
19 */
20
21 package com.allanbank.mongodb.client.connection.auth;
22
23 import com.allanbank.mongodb.Credential;
24 import com.allanbank.mongodb.client.connection.Connection;
25 import com.allanbank.mongodb.error.MongoDbAuthenticationException;
26
27 /**
28 * Authenticator provides the common interface for all MongoDB authenticators.
29 * <p>
30 * A single Authenticator instance will only ever be used with a single
31 * Connection and set of credentials. The "clone()" method is used to quickly
32 * allocate a new instance for a connection allowing for shared
33 * "preauthentication" work to be done.
34 * </p>
35 * <p>
36 * The {@link #startAuthentication(Credential, Connection)} method may assume
37 * that it is only invoked from a single thread. The "result" method should not
38 * make the same assumption.
39 * </p>
40 *
41 * @copyright 2013, Allanbank Consulting, Inc., All Rights Reserved
42 */
43 public interface Authenticator extends Cloneable {
44
45 /**
46 * Provides the ability to clone the authenticator. A new
47 * {@link Authenticator} instance is created for each physical connection in
48 * use.
49 * <p>
50 * Using clone allows users to create a "template" version of the
51 * authenticator that is then copied prior to use by each connection.
52 * </p>
53 *
54 * @return The cloned authenticator.
55 */
56 public Authenticator clone();
57
58 /**
59 * Returns the results of the authentication attempt.
60 *
61 * @return True if the user is successfully authenticated on the connection,
62 * false if the authentication fails.
63 * @throws MongoDbAuthenticationException
64 * On a failure in the protocol to authenticate the user on the
65 * connection.
66 */
67 public boolean result() throws MongoDbAuthenticationException;
68
69 /**
70 * Starts to authenticate the user with the specified credentials.
71 *
72 * @param credentials
73 * The credentials to use to login to the database.
74 * @param connection
75 * The connection to authenticate the user with.
76 * @throws MongoDbAuthenticationException
77 * On a failure in the protocol to authenticate the user on the
78 * connection.
79 */
80 public void startAuthentication(Credential credentials,
81 Connection connection) throws MongoDbAuthenticationException;
82 }