org.jickr
Class Auth

java.lang.Object
  extended by org.jickr.Auth

public class Auth
extends java.lang.Object

The Auth class is a set of static methods used to authenticate with Flickr.

Here's how to authenticate. First, you need a Flickr account.

For desktop, call the following from your code:


       Permission perm = Permission.READ; // For some value of Permission requested
       User user = Auth.getDefaultAuthUser();
       if (Auth.isAuthenticated(user,perm)) {
          Auth.setAuthContext(user);
       } else {
          System.out.println("Enter the following URL in your browser, then come back");
          System.out.println(Auth.getAuthURL(perm));
          user = Auth.authenticate();
          >wait here until they come back<
          Auth.isAuthenticated(user,perm);
          Auth.setDefaultAuthUser(user);
      }

For a multiuser, multithreaded environment like a servlet, call the following:


       Permission perm = Permission.READ; // For some value of Permission requested
       System.out.println("Enter the following URL in your browser, then come back");
       System.out.println(Auth.getAuthURL(perm));
       >wait here until they come back<
       User user = Auth.authenticate();

Then, in a different thread (i.e., a different servlet):

Auth.setAuthContext(user); >do the main action< Auth.resetAuthContext(); // clear the thread

These two code fragments do essentailly the same thing, the multithreaded environment just takes in account that you may have multiple users simultaneously.

Apply exception handling liberally above, since that's how Jickr reports problems, especially any problems accessing Flickr. For a working example, check out LoginTest.java in the examples.

Please note that the default behavior is to save the authentication tokens for users in a Java Preferences file (like the registry). If you do not have exclusive access to this file on your machine (whose location can vary from OS to OS), then please DO NOT USE THIS without altering it to make it secure in your environment. For most people, this level of security is probably sufficient, but please know what you're doing.


Method Summary
static User authenticate()
          Authenticate a a session, after the user has gone to the URL from getAuthURL().
static User getAuthContext()
          Get the AuthContext from this thread.
static java.lang.String getAuthURL(Permission perm)
          Authenticates user to Flickr.
static long getBandwidthMax()
          Get the bandwidth available for the current authenticated user.
static long getBandwidthUsed()
          Get the bandwidth used for the current authenticated user.
static User getDefaultAuthUser()
          Gets the default authenticated user.
static long getFilesizeMax()
          Get the max size of files allowed for the current authenticated user.
static Permission getPermLevel(User user)
          Gets the authentication level for a given user.
static boolean isAuthenticated(User authUser, Permission perm)
          Returns whether we're authenticated to at least this level.
static void resetAuthContext()
          Remove the AuthContext from this thread.
static void setAuthContext(User user)
          Set the AuthContext for this thread.
static void setDefaultAuthUser(User user)
          Sets the default authenticated user, for use in later executions of the program.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getAuthURL

public static java.lang.String getAuthURL(Permission perm)
                                   throws FlickrException
Authenticates user to Flickr. Requires additional action by the user afterward (i.e., visiting the URL in a browser). Note: Once a user is authenticated, that information is stored locally, and need not be called again unless changed, or revoked by Flickr. Jickr will disable authentication until you next call authenticate.

Parameters:
perm - The permissions this application needs.
Throws:
FlickrException - on any error getting the URL from Flickr.
See Also:
authenticate(), getFrob()

authenticate

public static User authenticate()
                         throws FlickrException
Authenticate a a session, after the user has gone to the URL from getAuthURL(). Also sets the authenticated context to be this authenticated user on this thread.

Returns:
The user we just authenticated.
Throws:
FlickrException - If anything goes wrong. This is also what will happen if getAuthURL wasn't visited.

isAuthenticated

public static boolean isAuthenticated(User authUser,
                                      Permission perm)
                               throws FlickrException
Returns whether we're authenticated to at least this level. If user is null, this will return false.

Parameters:
authUser - The the user to check for authentication. Null returns false.
perm - Permission to which we should be authenticated. Must not be null.
Returns:
Whether we're fully authenticated to perm level.
Throws:
FlickrException

getDefaultAuthUser

public static User getDefaultAuthUser()
                               throws FlickrException
Gets the default authenticated user. Convenience method for single-user usecases. Note that there is no guarentee if this user is still authenticated - use isAuthenticated(getDefaultAuthUser()) to check.

Returns:
Gets the default authenticated user. Null if unset.
Throws:
FlickrException

setDefaultAuthUser

public static void setDefaultAuthUser(User user)
                               throws FlickrException
Sets the default authenticated user, for use in later executions of the program. Convenience method for single-user usecases. Retrieved by getDefaultAuthUser().

Parameters:
user - The user to make the default. Null to clear value.
Throws:
FlickrException

getPermLevel

public static Permission getPermLevel(User user)
                               throws FlickrException
Gets the authentication level for a given user.

Parameters:
user - User to whose permissions to check.
Returns:
Permission level authenticated.
Throws:
FlickrException - On any error, or if not authenticated

setAuthContext

public static void setAuthContext(User user)
Set the AuthContext for this thread. Authenticated calls check the authcontext when determining who to execute a Flickr call as.

Parameters:
user - All calls will be made as this Authenticated user.
See Also:
authenticate(), getDefaultAuthUser()

resetAuthContext

public static void resetAuthContext()
Remove the AuthContext from this thread. Useful in multithreaded contexts.


getAuthContext

public static User getAuthContext()
Get the AuthContext from this thread.

Returns:
Authenticated user associated with this thread.

getBandwidthUsed

public static long getBandwidthUsed()
                             throws FlickrException
Get the bandwidth used for the current authenticated user.

Requires that the program be authenticated at READ level.

Returns:
The amount, in bytes, of bandwidth used.
Throws:
FlickrException - on any error.

getBandwidthMax

public static long getBandwidthMax()
                            throws FlickrException
Get the bandwidth available for the current authenticated user.

Requires that the program be authenticated at READ level.

Returns:
The amount, in bytes, of bandwidth available.
Throws:
FlickrException - on any error.

getFilesizeMax

public static long getFilesizeMax()
                           throws FlickrException
Get the max size of files allowed for the current authenticated user.

Requires that the program be authenticated at READ level.

Returns:
The amount, in bytes, of filesize available for use.
Throws:
FlickrException - on any error.