Seam Social Provides CDI Beans and extensions for interacting with a number of major social networks. Currently it provides these services and eases mixing them:
Seam Social 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 Java SE (desktop application).
If you are using Maven, you need to add the Seam Social core libraries to your pom.xml
:
<dependency> <groupId>org.jboss.seam.social</groupId> <artifactId>seam-social-api</artifactId> <version> ${seam.social.version}</version> <scope>compile</scope> </dependency> <dependency> <groupId>org.jboss.seam.social</groupId> <artifactId>seam-social</artifactId> <version> ${seam.social.version}</version> <scope>runtime</scope> </dependency>You also have to add specific dependencies on the services you need in your code
<dependency> <groupId>org.jboss.seam.social</groupId> <artifactId>seam-social-twitter</artifactId> <version> ${seam.social.version}</version> <scope>runtime</scope> </dependency> <dependency> <groupId>org.jboss.seam.social</groupId> <artifactId>seam-social-facebook</artifactId> <version> ${seam.social.version}</version> <scope>runtime</scope> </dependency> <dependency> <groupId>org.jboss.seam.social</groupId> <artifactId>seam-social-linkedin</artifactId> <version> ${seam.social.version}</version> <scope>runtime</scope> </dependency>
The Web example app is quite simple and gives a good idea of the possibilities with Seam Social. The main steps you need to take to use Seam Social are:
OAuthService
beanOAuthService
bean and initialize the access tokenShould you need to fully understand each step, the complete OAuth lifecycle can be found here or here.
To consume an OAuth service you need to declare an application on the service platform (i.e. for
Twitter you can do this at https://dev.twitter.com/apps/new. The declaration of an
application is done with the @OAuthApplication
annotation which must contain at least:
If you don't know what this is about, please refer to the OAuth concepts in your service documentation.
To use an OAuth Service Bean in Seam Social you need to provide the following configuration information
by producing the right OAuthService
bean:
The simplest way to configure your service is to create a producer method like so:
@OAuthApplication(apiKey = "FQzlQC49UhvbMZoxUIvHTQ", apiSecret = "VQ5CZHG4qUoAkUUmckPn4iN4yyjBKcORTW0wnok4r1k") @Twitter @Produces TwitterService twitterServiceProducer(TwitterService ts) { return ts; }
You can also create a bean by subclassing the implementation of the service like this:
@OAuthApplication(apiKey = "FQzlQC49UhvbMZoxUIvHTQ", apiSecret = "VQ5CZHG4qUoAkUUmckPn4iN4yyjBKcORTW0wnok4r1k") @Twitter public class MyTwitterBean extends TwitterServiceJackson { … }
The API key and API secret are provided by the service you want to consume (here Twitter). You can use the values above since they're coming from the "Seam Social" Twitter application. The callback depends on your application - it's the URL that will collect the OAuth verifier.
You can now inject the bean with the right service qualifier:
@Named @SessionScoped public class mySessionBean implements Serializable { ... @Inject @Twitter TwitterService service; ... }
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 rights to the application to use the service on their behalf the service will send you back a special code (verifier) that you must inject into the service to initiate the connection.
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 (the URL of which 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.twitterService.verifierParamName}" value="#{mySessionBean.twitterService.verifier}" required="true" requiredMessage="Error with Twitter. Retry later"/> <f:event type="preRenderView" listener="#{mySessionBean.twitterService.initAccessToken()}"/> </f:metadata>
The service is now connected - you have an access token.
Each OAuth Application needs a specific qualifier bearing the @ServiceRelated
Meta annotation.
Out of the box Seam Social provides one default OAuth application qualifier for each social services provides
(@Twitter
, @LinkedIn
, @Facebook
). Should you need to support more than one
application for a given service, you’d have to create a new service related qualifier (@TwitterMyApp
for instance). Please refer to the "Extending Seam Social" section to learn more about this.
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 OAuthService twiterService;
and
@Inject @Facebook OAuthService fbService;
Inject two different beans implementing the same interface (OAuthService).
JSON exchanges are managed by two beans:
JsonMapper
which deals with the implementation of JSON parser (Right now Jackson)JsonService
which has a higher function and uses JsonMapper
to provide
decoupling from the Json parser.Seam social uses the Generic bean functionality provided by Solder. Thus when you write :
@OAuthApplication(apiKey = "FQzlQC49UhvbMZoxUIvHTQ", apiSecret = "VQ5CZHG4qUoAkUUmckPn4iN4yyjBKcORTW0wnok4r1k") @Twitter @Produces TwitterService twitterServiceProducer(TwitterService ts) { return ts; }
The Generic extension creates the followings CDI beans with the same qualifier as the produced services
(@Twitter
in the example above) for you :
Seam Social provides a MultiServicesManager
bean that can help you to manage multiple services and
sessions for one user. Without this bean you’ll be able to have multiple services but only one session for each
service. The web app example application is a good starting point to learn how to use MultiServicesManager
bean.
Right now Seam Social comes with 3 basic service modules : Twitter, Facebook and LinkedIn. For this first Seam Social release (3.1.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.
To extend Seam Social by supporting a new service you’ll have to provide the following class or ressources :
@SocialRelated
meta annotation and the corresponding
literal. You’ll also need to create a properties file having the same name than your Qualifier. All of these
should reside in the org.jboss.seam.social
package.
OAuthService
interface. Extending the OAuthServiceBase
is
probably the easiest way to get it. It’s good practice to create an interface for this bean to have an easy way
to switch implementations if needed.
ServiceConfiguration
having the service qualifier. Implements the
getServiceClass()
method by returning the class you created in step 2.
The Facebook module is a good example of such an extension.