SecureSocial Demo with JPA
Java Scala
Permalink
Failed to load latest commit information.
app
conf
modules
project
public
test
.classpath_nb
.gitignore
README.rst

README.rst


SecureSocial Demo with JPA (or ssdemojpa for short) provides authentication via OpenID, OAuth/OAuth2 and userpass (username/password) in a ready-to-use implementation which employs SecureSocial (for actually doing the authentication) and JPA for the persistence layer.

Requirements

  • Java 8
  • Scala 2.10.4

Note: compilation will certainly fail with Scala 2.11.+

For the impatient

$ git clone http://github.com/frgomes/ssdemojpa
$ cd ssdemojpa
$ sbt
> metamodel
> compile
> run

Then point your browser to http://localhost:9000/ and login as shown below:

email:    admin@example.com
password: 12345678

You can also try these pages:

Foreword

PlayFramework employs Avaje Ebean as its default ORM technology but Avaje Ebean presents difficulties as soon as the entity model becomes to employ some "more advanced" features. For this reason EclipseLink was adopted as solution for the JPA layer. Notice that EclipseLink is the Reference Implementation (RI) adopted by the JEE stack.

EclipseLink provides a high level API, called Criteria API which allows type safe queries with information provided by metaclasses generated by EclipseLink from the entity classes you write. This concludes the matter for Java.

For the Scala world, there are interoperability issues with the Criteria API. For this reason, this project provides DAO classes which are meant to expose a high level API written in Java which can be integrated with a service layer written in Scala. This concludes the matter for Scala.

In addition, this project provides a SBT build script which generates metaclasses from entity classes. Also, a very simple integration with Twitter API is provided for the sake of example.

For basic documentation about how PlayFramework can be configured to work with EclipseLink, please consult these links:

Features is a Nutshell

  • userpass (i.e: username/password) authentication backed by JPA.
  • A simple service connects to Twitter and retrieves information related to tags you can inform. Point your browser to http://localhost:9000/trends in order to see it working.

Building this application

A SBT build script is provided in /project/Build.scala. This build script employs an annotation processor provided by EclipseLink which is reponsible for generating the metamodel from JPA entity classes. This is how you can build this application and run test cases:

$ sbt
> metamodel
> compile
> test

The SBT build script is also able to generate project files for major IDEs. This is how you can generate project files for Eclipse, Idea and Netbeans:

$ sbt
> eclipse
> idea
> netbeans

Organization of Source Code

Play! requires a project organization more or less like this:

/
+-- app
+-- conf
+-- project
    -- Build.scala
+-- test

We have added modules to this structure. Below we show some of the most relevant classes you will find:

/
+-- app
    +-- controllers
        +-- Application.scala
        +-- Authentication.scala
        +-- Waitress.scala
    +-- services
        +-- AuthenticationListener
        +-- AuthenticationService
+-- conf
    +-- application.conf
    +-- messages
    +-- securesocial.conf
    +-- META-INF
        +-- persistence.xml
+-- modules
    +-- models
        +-- app
            +-- dao
                +-- AbstractDAO.scala
                +-- IdentityDAO.scala
                +-- UserDAO.scala
            +-- models
                +-- AbstractModel.scala
                +-- Identity.scala
                +-- User.scala
    +-- services
        +-- app
            +-- services
                +-- TweeterService
        +-- test
+-- project
    -- Build.scala
+-- test

The idea is:

  1. app/controllers/Application.scala is intended to serve your home page and unprotected pages.
  2. app/controllers/Authentication.scala provides pages related to SecureSocial.
  3. app/controllers/Waitress.scala is your main controller, really.
  4. app/services contains services related to authentication, solely.
  5. modules/models contains Entity classes used by JPA and their corresponding DAO classes.
  6. modules/services/app/services contains services exposed by your application, but excludes services related to authentication.

Notes:

  • Data Access Objects (DAOs) are responsible for talking to the data model. The DAO layer is implemented in Java and it is responsible for providing convenience methods which wraps calls to the Criteria API. As mentioned above, attempting to call the Criteria API directly would imply on interoperability issues with Java.
  • The service layer is written in Scala and it is responsible for calling methods provided by the DAO layer and for maintaining transaction state. Contrary to PlayFramework documentation we do not employ @Transactional annotation in actions (web layer). Instead, we explicitly manage transactions in the service layer.

Configuration

  1. You are certainly interested on changing the title presented during the authentication. Just edit conf/messages.
  2. The file conf/securesocial.conf allows you to configure keys for accessing external authentication providers.

3. If you have turned on userpass, you will need an SMTP server for development. Instead of installing a full SMTP server, you can simply relay messages to your preferred SMTP server. A quick guide about this is available at http://rgomes-info.blogspot.co.uk/2014/03/configuring-postfix-for-relaying-on.html

Known issues

Authentication tokens should be shared in a cluster environment. The current implementation is not doing that yet, which is equivalent to say that this code is not ready yet for a production server in cluster.

Miscellaneous

SQL versus NoSQL

In case you are considering NoSQL and you are concerned about mixing SQL and NoSQL databases in your solution, I'd like to recommend these readings:

https://interlinked.org/tutorials/postgresql.html

http://sourceforge.net/apps/mediawiki/postgres-xc

Support

Please find links on the top of this page.