There are two ways to use the jboss idm.
- Use it as the embedded way.
- Deploy it into the container (JBoss AS5), and then all other projects are using it through getting IdentitySessionFactory from JNDI.
Well, for the 1st case, users need to use the API to start the IdentitySessionFactory, and then use it. The code is as following, which you can find on the example module.
IdentitySessionFactory identitySessionFactory = new IdentityConfigurationImpl().
IdentitySession identitySession = identitySessionFactory.createIdentitySession("realm://JBossIdentityExample/SampleRealm");
And then use the IdentitySession to do the operations etc. So it is very easy to use.
Now, lets look at the second case, by deploying the idm into the JBoss AS 5. Here we take the SOA Platform as an example to illustrate this use case, as we will ship the SOA Platform to include the idm component by default, so that other projects, namely jBPM, SOA Repository can share the identity component, instead of having its own seperate identity component.
The jobs that need to be done for the deployment in the container is quite simple:
- Populate the idm schema if neccessary.
- Start the IdentitySessionFactory, and then register it into the JNDI.
Before we look at it further, lets see the configuration files that jboss idm needed typically. (Say using db back-end, hibernate impl combination)
- jboss idm configuration file. say jboss.idm.cfg.xml
- datasource file, say idm-ds.xml
- hibernate cfg file, say jboss.idm.hibernate.cfg.xml.
With regard to the detail of jboss idm configuration file, you can refer to the configuration page.
So, if we want to deploy the idm into container with a specified JNDI name, we need to have a deployment file to define the JNDI and other neccessary properties.
For the integration with JBoss AS5, the AS5 has a great deployment feature, we've built our own deployer to extend it, so that the AS can listen on the -jboss-idm.xml suffix file to start the IdentitySessionFactory.
Basically, we had two deployer, one is: IDMConfigParsingDeployer class, which is taking responsible for parsing files that ends with the -jboss-idm.xml suffix into Java object. The other is: IDMDeployer class, this one is to do the real job, which means it might populate the schema, initial dataset into target db, and then start the IdentitySessionFactory, register it into the JNDI with the specified name at last.
we will see a very typical deployment file looks like. (default-jboss-idm.xml)
<?xml version="1.0" encoding="UTF-8"?>
<exitSQL>select * from jbid_io</exitSQL>
- The deployment file must be named -jboss-idm.xml as suffix, otherwise, it won't be recoginzed in the JBoss AS5 container.
- The "JNDIName" and "idmConfigFile" attributes are required. The JNDIName is the name for keeping the started IdentitySessionFactory.
- The hibernateDeployer is optional, the reason that why we had the hibernateDeployer is that we can reuse the hibernateSessionFactory in the jboss idm configuration file.
- The Initializer is optional, it is responsible for populating the db schema and initialized dataset if any.
detailed information about the deployment file is specified in the identity-deployer.xsd file.
Once you've deployed the idm into JBoss AS5, by using the distribution. It will copy the idm-deployer into the JBoss AS5/server/$config/deployers folder, and the idm folder into the JBoss AS5/server/$config/deploy folder, which contains the default configuration files, like the jboss.idm.cfg.xml, idm-ds.xml etc.