Declaring OAuth configuration

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). The declaration of an application is done with @OAuthApplication annotation which contains at least :

• 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.

About Services Hub bean and Service API

Most Social Media have a lot APIs that are categorized by families. For instance Twitter has APIs for Timeline, Search, Direct Messages, etc...
Agorava tries to stay close to this organisation, so each of these APIs families are organize in a given class (Bean in CDI). That's why we got TwitterTimelineService, TwitterUserService, etc...
As there could be dozen of services classes for a given Social Media Agora needs a federating mechanism to gather all those API. That's the ServicesHubs role.
Hubs also provides polymorphic services across all Media Services. Thru SocialServicesHub interface you can fullfil the OAuth connexion or get your account without neeing to know what is the actual service. We plan to provide other transverse services like update posting or basic timeline reading.

Producing a socialServiceHub to bootstrap a social media

So ServicesHub are the entry point to configure a Social Media et access to its APIs. Thus To use an Service Bean in Agorava you need to provide OAuth configuration information by producing the right SocialNetworkServiceHub bean* thru a producer method.

public class HubProducer {
    @Twitter
    @OAuthApplication(params = {@Param(name = OAuthAppSettingsBuilder.API_KEY, value = "<your API Key>"),
            @Param(name = OAuthAppSettingsBuilder.API_SECRET, value = "<your API secret key>")})
    @Produces
    public SocialMediaApiHub twitterProducer(TwitterServicesHub service) {
        return service;
    }
}

twitter.apiKey=<your key>
twitter.apiSecret=<your secret key>
twitter.callback=/twittercallback.jsf

facebook.apiKey=<your key>
facebook.apiSecret=<your secret key>
facebook.scope=<needed scope>

linkedin.apiKey=<your key>
linkedin.apiSecret=<your secret key>

callback=/globalcallback.jsf

@Twitter
@OAuthApplication(builder = PropertyOAuthAppSettingsBuilder.class,
          params = {@Param(name = PropertyOAuthAppSettingsBuilder.PREFIX, value = "twitter")})
@Produces
public TwitterServicesHub twitterProducer(TwitterServicesHub service) {
     return service;
}

Inject the Services Hub Bean in your code

You can now inject the services hub and specific apis

@Named
@SessionScoped
public class mySessionBean implements Serializable {
...
    @Inject
    @Twitter
    SocialNetworkServicesHub serviceHub;

    @Inject
    TwitterTimelineService tl;

    @Inject
    TwitterUserService userService;
...
  }
}

Request the OAuth authorization URL

You can now ask for the authorization URL for your service

String authURL = service.getAuthorizationUrl();

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 you have to inject in the serviceHub to initiate the connexion.

Set the verifier and initiate connexion

As the verifier comes back to the application after an action of the final user, you have to set up a servlet or a JSF page (which url is the callback url you configured when you set up the service) to catch it and add it to the current session. Here is an example with JSF :

<f:metadata>
  <f:viewParam name="#{mySessionBean.serviceHub.verifierParamName} "
   value="#{mySessionBean.serviceHub.verifier} "
   required="true" requiredMessage="Error with Twitter. Retry later"/>
  <f:event type="preRenderView" listener="#{mySessionBean.serviceHub.initAccessToken()} "/>
</f:metadata>

The service is now connected : you have an acces token.

Send request to the service

you can now use the service on behalf of the user who gave right to your OAuth application

TwitterProfile user = twitterServiceHub.getMyProfile();
String fullName = user.getFullName();

Service Qualifiers

Each OAuth Application needs a specific qualifier bearing the @ServiceRelated Meta annotation. Out of the box Agorava provides one default OAuth application qualifier for each social services provides (@Twitter, @LinkedIn, @Facebook). We will provide a way to support usage of multiple OAuth application for a given service in a near futur.
Those qualifiers will be used on all the bean attached to a given OAuth application. They are useful to avoid ambiguous injection in the generic part of the API :

@Inject
@Twitter
SocialNetworkServicesHub twitterHub

and

@Inject
@Facebook
SocialNetworkServicesHub facebookHub;

Inject two different beans implementing the same interface (SocialNetworkServicesHub) for 2 different Social Media (Twitter and Facebook).

Basic JSon Beans and modules

Json exchanges are managed by the bean JsonMapper which deal with implementation of JSon parser. We use Jackson framework for JSON mapping, so JsonMapper bean also deal with global Jackson configuration.

Beans created by @OAuthApplication

Agorava uses JBoss Solder Generic Bean functionality. Thus when you write :

@OAuthApplication(apiKey = "<your API key here>", apiSecret = "<your API secret key here", callback="<your callback url or oob>")
@Twitter
@Produces
TwitterService twitterServiceHubProducer(TwitterServicesHub ts)
{
  return ts;
}

The Generic extension creates the followings CDI beans with the same qualifier than the produced services (@Twitter in the example above) for you :

• SocialNetworkServicesHub : the producer creates this first bean. It’s the center of all Social Media exchange as we saw before.

• OAuthService : This bean deals with high level OAuth exchange with given social media. It calls more basic function in OAuthProvider it ues Settings to initiate connexion and then uses Session information and JSon Mapper bean to transform exchange to and from object

• OAuthServiceSettings : this bean has the same scope than the service and contains all the configuration of the OAuth Application plus the Service Related Qualifier of the service

• OAuthProvider : this bean has the same scope than the service. It contains all the basic function to deal with OAuth like creation of token, request signature. It’s main purpose is to deal with implementation of OAuth management library (right now Java-Scribe)

• OAuthSession : this session scoped bean contains all the OAuth Information needed to interact with remote service. Mainly the AccessToken.

Working with Multi Service Manager

Agorava provides a MultiServicesManager bean that can help you to manage multiple services and session for one user. Without this bean you’ll be abble to have multiple services but only one session for each service.
The Socializer web app example application is a good starting point to learn how to use MultiServicesManager bean

Provided modules

Right now Agorava comes with 3 basic service modules : Twitter, Facebook and LinkedIn. For this first Agorava version (0.5.0), our main goal was to create a good core API for identification so provided modules have very basic functionalities. Check the JavaDoc to learn about them.
We’ll provide more functionalities and modules for the next release.

Extending Agorava

Agorava is thought to be extended with new Social Media modules. Right now we decided to wait before creating new modules. Core API are about to change with integration of JAX-RS 2.0 client framework so we will focus on these module when version 1.0.0 will be released.