HomeDownloadsUser GuideDevelopment

User Guide: Examples

Your OpenPermis distribution includes an examples folder which contains all the examples listed below.

Notes

Care has been taken to create the examples as self-explanatory as possible. If appropriate each example includes:

  • readme.txt a short introduction to the example.
  • build.xml an ANT build file to simplify building and executing.
  • src/ the folder containing the actual example sources.
  • resources/ additional resources required for the example.

You have to execute 'ant' in the 'examples/common' directory before starting running the examples

The classes that are used in more than one example have been moved to the 'examples/common' directory. To be able to run any example you have first to go to that directory and execute the command 'ant' to compile them!

Simple

This example is explained in detail in the ten minute tutorial, however, you can quickly run it from both Eclipse or the distribution.

To run it from the distribution, go to the example's distribution directory and then execute 'ant' to generate the certificates and 'ant run' to run the example.

To run it from Eclipse execute './build.sh examples-simple.certs4ide' from the projects root and then execute the main method of the 'examples/simple/HelloWorld.java' file.

XACML

This example shows quickly how a OpenPermis authorization service is created, which takes XACML-Requests and returns XACML-Responses.
A detailed description of the OpenPermis XACML support can be found in section architecture xacml.

To run it from the distribution, go to the example's distribution directory and then execute 'ant compile' to compile and 'ant run' to run the example.

Check out and run the integration project before trying to run the server examples manually!

If you want to run the ejb or the ldap examples, which require respectively a JEE and an LDAP server configured and running, we strongly advice you to check out and set up the integration project and to run its shell scripts first, since they already do it automatically. So: go to integration before continuing with this page!

EJB

Example that shows how to separate the authorization service and the client using it as an EJB3 application.
The example includes all files necessary to build and test the application using a JBoss 5.x.

You will need an EJB server to compile and run this example. The example has been tested and pre-configured to work JBoss 5.x and consists of a simple EJB3 bean and a rich client.

Preparations taking advantage of the integration project

  1. check out the integration project
  2. run 'run-integration.sh' at the project's root once
  3. open 'run-javaee-integration.sh' in the 'src/javaee' directory of the integration project
  4. comment out the twenty last lines which shut down and erase the server
  5. run the modified script
  6. be aware of the fact that if you want to re-run the script to restart the server you now have to first stop and remove the running server instance by executing manually the shutting and deleting commands you commented out.
  7. if you accidentally removed the server directory before running the server stopping script it contains, kill the server's java process.

Preparations not taking advantage of the integration project

  1. Download and install a JBoss 5.x.
  2. Start the JBoss 5.x server.
  3. Make sure the server is up and running.
  4. Move the working directory of your terminal to the 'examples/ejb' folder of the distribution.
  5. Adjust the 'server.xml' file in the toplevel folder of the example.
  6. Execute 'ant deploy' to compile and deploy the EJB to your server.

Once the example is deployed you should see the following server output:

hello-permis/HelloWorldService/remote - EJB3.x Default Remote Business Interface
hello-permis/HelloWorldService/remote-org.openpermis.examples.ejb.server.HelloWorldServiceRemote - EJB3.x Remote Business Interface

Compiling/Starting the Client

  1. Execute 'ant client'.

A simple Swing-based GUI will give you the option to choose between user "john" or "sara". The EJB is configured to grant permission to "john" while "sara" does not have permission.

Modifying the Example

To keep the example small and simple the resources and configurations used are mostly hard-coded in the client and server classes. However since those classes are small and there are not many resources you should be able to modify the classes or use them as a starting point for your own implementation.

The resources for the PDP which is embedded in the EJB are stored in the 'resources' folder. The certificates read and the policy ace file used are hard-coded in the org.openpermis.examples.ejb.server.HelloWorldService.

The users offered at the client chooser are hard-coded in the client class org.openpermis.examples.ejb.client.HelloWorldClient.

The following configuration files might also be of interest to you:

  1. config/server/application.xml (template for the application.xml of the EJB)
  2. config/client/jndi.properties (client jndi.properties)

Build Commands

The following build targets are available:

all
Builds and deploys the EJB and starts the client
clean
Removes all build artifacts
compile
Compiles the client and the server classes
ear
Builds the server EAR
deploy
Deploys the EAR on the server
client
Runs the client

LDAP

This example shows how to use an LDAP server as your storage location for policies and certificates. You can run this example from the IDE by executing the class HelloLdap or from the distribution by going to the 'examples/ldap' directory and by executing first 'ant' ant then 'ant run'.

Both ways of executing the example requires the LDAP server to be configured and running. To configure and start the LDAP server follow the following steps:

  1. check out the integration project
  2. run 'run-integration.sh' at the project's root once
  3. open 'run-ldap-integration.sh' in the 'src/ldap' directory of the integration project
  4. comment out the eight last lines which shut down and erase the server
  5. run the modified script
  6. be aware of the fact that if you want to re-run the script to restart the server you now have to first stop and remove the running server instance by executing manually the shutting and deleting commands you commented out.
  7. if you accidentally removed the server directory before running the server stopping script it contains, kill the server's java process.