com.evernote.edam.userstore
Interface UserStore.Iface

All Known Implementing Classes:
UserStore.Client
Enclosing class:
UserStore

public static interface UserStore.Iface

Service: UserStore

The UserStore service is primarily used by EDAM clients to establish authentication via username and password over a trusted connection (e.g. SSL). A client's first call to this interface should be checkVersion() to ensure that the client's software is up to date.

All calls which require an authenticationToken may throw an EDAMUserException for the following reasons:


Method Summary
 AuthenticationResult authenticate(java.lang.String username, java.lang.String password, java.lang.String consumerKey, java.lang.String consumerSecret)
          This is used to check a username and password in order to create an authentication session that could be used for further actions.
 boolean checkVersion(java.lang.String clientName, short edamVersionMajor, short edamVersionMinor)
          This should be the first call made by a client to the EDAM service.
 PublicUserInfo getPublicUserInfo(java.lang.String username)
          Asks the UserStore about the publicly available location information for a particular username.
 User getUser(java.lang.String authenticationToken)
          Returns the User corresponding to the provided authentication token, or throws an exception if this token is not valid.
 AuthenticationResult refreshAuthentication(java.lang.String authenticationToken)
          This is used to take an existing authentication token (returned from 'authenticate') and exchange it for a newer token which will not expire as soon.
 

Method Detail

checkVersion

boolean checkVersion(java.lang.String clientName,
                     short edamVersionMajor,
                     short edamVersionMinor)
                     throws org.apache.thrift.TException
This should be the first call made by a client to the EDAM service. It tells the service what protocol version is used by the client. The service will then return true if the client is capable of talking to the service, and false if the client's protocol version is incompatible with the service, so the client must upgrade. If a client receives a false value, it should report the incompatibility to the user and not continue with any more EDAM requests (UserStore or NoteStore).

Parameters:
clientName - This string provides some information about the client for tracking/logging on the service. It should provide information about the client's software and platform. The structure should be: application/version; platform/version; [ device/version ] E.g. "Evernote Windows/3.0.1; Windows/XP SP3" or "Evernote Clipper/1.0.1; JME/2.0; Motorola RAZR/2.0;
edamVersionMajor - This should be the major protocol version that was compiled by the client. This should be the current value of the EDAM_VERSION_MAJOR constant for the client.
edamVersionMinor - This should be the major protocol version that was compiled by the client. This should be the current value of the EDAM_VERSION_MINOR constant for the client.
clientName -
edamVersionMajor -
edamVersionMinor -
Throws:
org.apache.thrift.TException

authenticate

AuthenticationResult authenticate(java.lang.String username,
                                  java.lang.String password,
                                  java.lang.String consumerKey,
                                  java.lang.String consumerSecret)
                                  throws EDAMUserException,
                                         EDAMSystemException,
                                         org.apache.thrift.TException
This is used to check a username and password in order to create an authentication session that could be used for further actions.

Parameters:
username - The username (not numeric user ID) for the account to authenticate against. This function will also accept the user's registered email address in this parameter.
password - The plaintext password to check against the account. Since this is not protected by the EDAM protocol, this information must be provided over a protected transport (e.g. SSL).
consumerKey - A unique identifier for this client application, provided by Evernote to developers who request an API key. This must be provided to identify the client.
consumerSecret - If the client was given a "consumer secret" when the API key was issued, it must be provided here to authenticate the application itself.
username -
password -
consumerKey -
consumerSecret -
Returns:
The result of the authentication. If the authentication was successful, the AuthenticationResult.user field will be set, but that User's 'attributes' will not be set. To retrieve the full information about the User, including its UserAttributes, make a separate call to UserStore.getUser() with the authentication from this call.
Throws:
EDAMUserException -
  • DATA_REQUIRED "username" - username is empty
  • DATA_REQUIRED "password" - password is empty
  • DATA_REQUIRED "consumerKey" - consumerKey is empty
  • INVALID_AUTH "username" - username not found
  • INVALID_AUTH "password" - password did not match
  • INVALID_AUTH "consumerKey" - consumerKey is not authorized
  • INVALID_AUTH "consumerSecret" - consumerSecret is incorrect
  • PERMISSION_DENIED "User.active" - user account is closed
EDAMSystemException
org.apache.thrift.TException

refreshAuthentication

AuthenticationResult refreshAuthentication(java.lang.String authenticationToken)
                                           throws EDAMUserException,
                                                  EDAMSystemException,
                                                  org.apache.thrift.TException
This is used to take an existing authentication token (returned from 'authenticate') and exchange it for a newer token which will not expire as soon. This must be invoked before the previous token expires.

Parameters:
authenticationToken - The previous authentication token from the authenticate() result.
authenticationToken -
Returns:
The result of the authentication, with the new token in the result's "authentication" field. The User field will not be set in the reply.
Throws:
EDAMUserException
EDAMSystemException
org.apache.thrift.TException

getUser

User getUser(java.lang.String authenticationToken)
             throws EDAMUserException,
                    EDAMSystemException,
                    org.apache.thrift.TException
Returns the User corresponding to the provided authentication token, or throws an exception if this token is not valid. The level of detail provided in the returned User structure depends on the access level granted by the token, so a web service client may receive fewer fields than an integrated desktop client.

Parameters:
authenticationToken -
Throws:
EDAMUserException
EDAMSystemException
org.apache.thrift.TException

getPublicUserInfo

PublicUserInfo getPublicUserInfo(java.lang.String username)
                                 throws EDAMNotFoundException,
                                        EDAMSystemException,
                                        EDAMUserException,
                                        org.apache.thrift.TException
Asks the UserStore about the publicly available location information for a particular username.

Parameters:
username -
Throws:
EDAMUserException -
  • DATA_REQUIRED "username" - username is empty
EDAMNotFoundException
EDAMSystemException
org.apache.thrift.TException