Prerequisites:

* You must have the dependency manager Maven 2 installed.
* To build in eclipse you must have m2eclipse plugin installed.

Instructions:

To build at the command prompt, in the root of this project type: mvn install
To build in Eclipse, select Import > Existing Maven Projects 

If you are a doing a web server callback flow, read this first:

http://wiki.developerforce.com/page/Digging_Deeper_into_OAuth_2.0_on_Force.com

If you are doing a username and password flow, read this first:

https://login.salesforce.com/help/doc/en/remoteaccess_oauth_username_password_flow.htm

If you are looking to refresh an expired session:

https://login.salesforce.com/help/doc/en/remoteaccess_oauth_refresh_token_flow.htm#request_access_token

You can run the username and password flow from the class UsernamePasswordFlow as a J2SE application.  Simply provide the instance name, the consumer key (client id), and the consumer secret (client secret) to instantiate the class.  Then provide a username and password to get an access token, which serves as a session ID for any API reqeust to Salesforce.  To pass the access token to Salesforce and overcome an HTTP 401 Unauthorized message, set the HTTP header "Authorization: OAuth xxxxxxx-your-access-token-xxxxxxxx".

You can run the callback flow from the class HerokuApp.java, which contains a main() method that lets you start the server from the command line.  The main method has an embedded web container from Jetty, so it is initiating its own HTTP server.  Specify an environment variable on your system called $PORT and you can configure which port the server will listen on.  You don't need to package this web app in a WAR and put it on Tomcat, Jboss, or your favorite web container like in a traditioanl web app, but you certainly could.  This server will run locally, and it is also 100% ready to deploy on Heroku.  There is a configuration file in the root of the project called Procfile that tells Heroku what to run.  For more information see:

http://devcenter.heroku.com/articles/java

The callback servlet is implemented in CallbackServlet.java.  Here is the flow:

1) Client makes an HTTP GET request to CallbackServlet 
2) Callback servlet redirects client request to Salesforce
3) Client enters credentials
4) Salesforce returns a response with a redirect to CallbackServlet, plus a parameter on the URL named 'code'
5) CallbackServlet sees the authorization code, then calls out to Salesforce for a session ID
6) CallbackServlet responds some with data about the user, like recent chatter status.

If you are running this app on Heroku, be sure to run these commands:

heroku config:add HOSTNAME=your.website.com
heroku config:add CLIENT_ID=xxxx-your-key-blah
heroku config:add CLIENT_SECRET=xxxx-your-secret-from-salesforce-remote-sites
git push heroku master

If you are running the HerokuApp.java out of Eclipse, you can set environment variables in the run configurations.  The tests will also require these.