Agorava’s roadmap contains CDI and other JSR 330 implementations. Right now CDI implementation is the only one developed, so this "getting started" document is only focused on CDI. Other implementations will be released after Agorava 1.0.0. Stay tuned or don’t hesitate to contribute to these implementations.
Agorava Provides CDI Beans and extensions to interact with major social network. It provides these services and eases mixing them:
A generic portable REST client API
A generic API to deal with OAuth 1.0a and 2.0 services
A generic API to work with JSON serialization and de-serialization
A generic identification API to retrieve basic user information from a Social Service
Specific API for Twitter, Facebook and LinkedIn
A multi services manager API allowing to deal with multiple OAuth applications and sessions in the same application and in different mode (by web user, in batch mode… )
An easy way to extend it by creating a new module for a new services using Agorava SPI.
Agorava is independent of CDI implementation and fully portable between Java EE 6 and Servlet environments enhanced with CDI. It can be also used with CDI in JSE (desktop application). It has been fully tested with CDI RI implementation (JBoss Weld) and Apache OpenWebBeans. Caucho Candi was not fully tested yet but will be in the coming releases.
Agorava is available in Maven Central repository. We don’t provide official binaries you can download. Let us know if you need them
To use Agorava you’ll have to add Agorava core libraries in your pom :
<dependency>
<groupId>org.agorava</groupId>
<artifactId>agorava-core-impl-cdi</artifactId>
<version>0.7.0</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.agorava</groupId>
<artifactId>agorava-core-api</artifactId>
<version>0.7.0</version>
<scope>compile</scope>
</dependency>
You also have to add specific dependencies on the services you need in your code For Twitter :
<dependency>
<groupId>org.agorava</groupId>
<artifactId>agorava-twitter-api</artifactId>
<version>0.7.0</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.agorava</groupId>
<artifactId>agorava-twitter-cdi</artifactId>
<version>0.7.0</version>
<scope>runtime</scope>
</dependency>
For Facebook
<dependency>
<groupId>org.agorava</groupId>
<artifactId>agorava-facebook-api</artifactId>
<version>0.7.0</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.agorava</groupId>
<artifactId>agorava-facebook-cdi</artifactId>
<version>0.7.0</version>
<scope>runtime</scope>
</dependency>
And for LinkedIn
<dependency>
<groupId>org.agorava</groupId>
<artifactId>agorava-linkedin-api</artifactId>
<version>0.7.0</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.agorava</groupId>
<artifactId>agorava-linkedin-cdi</artifactId>
<version>0.7.0</version>
<scope>runtime</scope>
</dependency>
As you’ll be using CDI implementation you’ll also have to have a CDI compliant environment (Java EE 6 server or bootstrap CDI like Weld-SE or Deltaspike bootstrap)
The Socializer demo web app is quite simple and give a good idea of possibilities of Agorava Framework. You should give it a try. Main steps to use Agorava are :
Declare your OAuth application on the Social Media web site you want to use
Produce an OAuthAppSettings with a CDI producer with the OAuth app keys
Declare how your OAuth Sessions will be resolved by configuring the producerScope property in Agorava.properties on JNDI
Call the startDanceFor(<serviceName>) method of OAuthLifeCycleService bean to get the Authorization URL to redirect end user to
Let the callBack servlet retrieve retrieve info from service and finish the OAuth dance
Use the service API
Should you need to fully understand each step, the complete OAuth lifecycle can be found on Twitter developer site or LinkedIn developer site.
For a deeper comprehension you can check RFC for OAuth 1.0a and OAuth 2.0
Points above are detailed below
To consume an OAuth service you need to declare an application on the service platform (i.e. for Twitter you can do, this on https://dev.twitter.com/apps/new). After this declaration you’ll get at least 2 keys to consume your OAuth service :
an OAuth API public key
an OAuth API private/secret key
If you don’t know what this is about, please go check the OAuth concepts on your service documentation.
The OAuthAppSettings are the entry point to configure a Social Media. It indicates to Agorava Framework that the service is activated and that you you can use its service beans. Usually you create this OAuthAppSettings thru a CDI producer method and by using OAuthAppSettings builder like this, like this :
Using the @OAuthApplication annotation you can produce your setting like that :
@ApplicationScoped
@Produces
@Twitter
@OAuthApplication(builder = SimpleOAuthAppSettingsBuilder.class,
params = {@Param(name = OAuthAppSettingsBuilder.API_KEY, value = "<Consumer Key>"),
@Param(name = OAuthAppSettingsBuilder.API_SECRET, value = "<Consumer Secret>"),
})
OAuthAppSettings settings;
You can also use the default mechanism based on a properties file
All you have to do is to provide an agorava.properties file in your classpath with the following content :
twitter.apiKey=<your key> twitter.apiSecret=<your secret key> facebook.apiKey=<your key> facebook.apiSecret=<your secret key> facebook.scope=<needed scope> linkedin.apiKey=<your key> linkedin.apiSecret=<your secret key> callback=callback
Now you can produce Twitter OAuthAppSettings like this
@ApplicationScoped
@Produces
@Twitter
@OAuthApplication(params = {@Param(name = OAuthAppSettingsBuilder.PREFIX, value = "twitter")})
public OAuthAppSettings twitterSettings;
OAuthSession contains all user information regarding an OAuth Access (each OAuthSession get a specific access token to access a specific OAuth application on the behalf of the user who granted access to her account).
OAuthSession beans are a stateful sensitive data mandatory for all OAuth exchange. As OauthSession need to have a @Dependent scope (no scope or 'prototype' scope if you prefer), all OAuthSession`of a given Agorava user are stored in a `UserSessionRepository which much store in a place that allow it to be fetch when needed. For that purpose Agora provide different UserSessionRepositoryResolver and SessionResolver that you can activate by configuration. You can also create your own resolver but it’s beyond this tutorial.
Built-in resolver strategy are :
session : the UserSessionRepository is stored in Http Session (@SessionScoped) it was the Agorava behavior before version 0.7.x
request : the UserSessionRepository is provided for the current Http Request (@RequestScoped) but you have to propagate the repoid url parameter with UserSessionRepository.getId() value to retrieve the repo at each request
cookie : the UserSessionRepository is provided for the current Http Request (@RequestScoped), a cookie is used on user browser to keep the track of her UserSessionRepository. You can specify the lifetime of the cookie int he config
application : the UserSessionRepository is provided for all the application time (@ApplicationScoped). Not suitable for a multi-user scenario but rather for desktop scenario or a web app providing a shared access to a unique Social Network
To activate the resolver of your choice you have to add it to agorava.properties file
resolver=session
cookie resolver create by default a cookie which lifetime is tied to the browser (cookie destroyed when browser closed). You can change this like this
resolver=cookie cookie.life=31536000 #cookie maxAge in seconds
You can now inject the social network specific apis
@Named
public class mySessionBean implements Serializable {
...
@Inject
@Twitter
TwitterTimelineService tl;
@Inject
@Twitter
TwitterUserService userService;
...
}
Using the OauthLifecycleService bean you can now ask for the authorization URL for your service
@Inject
OAuthLifeCycleService lifeCycleService;
String authURL = lifeCycelService.startDanceFor("Twitter");
//or
String authURL = lifeCycelService.startDanceFor(Twitter.class);
Calling this URL will bring the user on the service connection page and right delegation for the application. If the user gives right to the application to use the service on her behalf the service will send the browser back a special code (verifier) that built in OAuthCallBackServlet use to end the OAuth Dance.
By default the callback from social media is handle by the callback servlet which is mapper to /callback url. The servlet will get the verifier back from the service and request the access token.
The after this, the servlet redirect the user to the internal call back page. This callback should also be definied in agorava.properties file like this
internalcallback=/icallback.jsf
It can also be defined when calling OAuthLifeCycleService.startDancefor() method to decide the returning url at runtime.
The service is now connected : you have an access token.
During the connection Agorava automatically get your user profile. You can get it thru the OAuthSession :
@Inject @Current OAuthSession session; UserProfile user = session.getUserProfile(); String fullName = user.getFullName();
you can now use the service on behalf of the user who gave right to your OAuth application
public class myTweetBean implements Serializable {
@Inject
TwitterTimelineService tl;
public Tweet sendTweet(String msg)
{
return tl.updateStatus(msg);
}
}
Our example application Socializer use all these technics, so don’t forget to check the code of the application (3 classes, 3 JSF pages and 1 config file) to see how all of this works together
Whatever resolver you choose, Agorava maintains a GlobalRespository in @ApplicationScoped. This repo contains all the UserSessionRepository of the application. so you use it to access all OAuthSession on server side to provide batch processing on them.
Right now Agorava comes with 3 basic social media modules:
Other non officials modules are being developed:
Agorava is thought to be extended with new Social Media modules. Core API are now quite stable so it can be extended in its core or by providing new modules. Stay tuned to check our coming contributor documentation