Want to create a new agent for a container? How to add a new agent to the J2EE agent workspace?

This is similiar whether you are creating a new agent form scratch or moving an agent from internal Sun workspace out into opensource workspace.
I will use an example here, of adding a Tomcat 6 agent. You would need to do very similar things for another web application server.

1) Join opensso project
you need to get a java.net id and then login and then join the opensso project and ask for developer role https://opensso.dev.java.net/servlets/ProjectMembershipRequest
this will allow you to file issues and later commit code. Should be approved in a little bit.

Also, join some mailing lists https://opensso.dev.java.net/servlets/ProjectMailingListList
like
dev@opensso.dev.java.net
code-review@opensso.dev.java.net
and maybe users@opensso.dev.java.net

2) Make sure you are working in the right branch
The 3.0 agents are in the tip of the workspace so no branch needs to be specified.

The 2.2 agents are in another branch
Always be sure you are using a 2.2 branch checkout. Please use branch tag opensso_agent22_branch
Checkout whole branch so cvs checkout opensso for branch 2.2 since you also want the all the code for 2.2 agents, not just agents code.
The j2ee agent source is under products/j2eeagents.

3) Add code and files and diretcory structure and build
opensso build is just basic ant.
Probably best to start by maybe building the weblogic agent, or just following its structure as a template, maybe look inside opensso\products\j2eeagents\build.xml and just follow the target for "ant weblogic_v10" and then you will do similiar steps for adding somthing like a tomcat_v6 target. Directory structure would be very similiar to weblogic agent also. The appserver_v9 target for Sun app server is also very similiar to weblogic, but app server build is a bit strange since it uses same code for v9 and v8 targets so is less suitable to copy- weblogic is more straight forward. We try to keep all agents mostly same unless exceptional cases.

I will describe a brief flow of weblogic_v10 build target and directory structure so you have a small map when looking through:

3-a) create a directory structure inside opensso\products\j2eeagents\ that is very similiar to weblogic
opensso\products\j2eeagents\
opensso\products\j2eeagents\tomcat
Then the main one,
opensso\products\j2eeagents\tomcat\v6
and the sub-directories under opensso\products\j2eeagents\tomcat\v6
which have all the tomcat agent specific code and artifacts
You wont need an mbeans/ directory as this is specific to weblogic so ignore it, otherwise you will use same directories place code and config files in those directories (similiar to weblogic) and distribute config files etc as you see in weblogic directories(mostly same as internal but some config files in slightly different places)
Note, the directory opensso\products\j2eeagents\weblogic\v10\extlib or in your case
opensso\products\j2eeagents\tomcat\v6\extlib contains a file called .cvsignore and just copy it into your opensso\products\j2eeagents\tomcat\v6\extlib
In a later step, you will use opensso\products\j2eeagents\tomcat\v6\extlib\ as the place to copy any jar files needed to build the agent (these jars are not checked in as they are kept in each developers personal workspace)

3-b) opensso\products\j2eeagents\ has an ant files you need to modify
build.xml has some targets for weblogic_v10 and need similiar for tomcat_v6
this build file mostly calls other build file so targets are simple

3-c) opensso\products\j2eeagents\weblogic\
or opensso\products\j2eeagents\tomcat\ in your case
has a build file, do same thing for tomcat, make small modifications replace weblogic with tomcat

3-d) opensso\products\j2eeagents\weblogic\v10
or opensso\products\j2eeagents\tomcat\v6 in your case
has a build file. This build file does most of the work for the specific agent for this specific server version, whereas the other build files did things like build the common code in agentsdk and made a jar file etc that is done for all agents, now this build file will build your source code by copying things into the right places etc.

3-e) Now you need to add some agent specific code that does some things like the installer, uses the agentsdk and clkientsdk, and integrates into your server platform security APIs to for example get credentials for J2EE security mechanisms.
*most of the code for an agent is common and is included in the agentsdk. Your agent will need to do a few extra things specific to that agent.
*implement some of the agent installer classes. The agents have a common installer and for each agent you need to implement some classes and some configuration files so that this agent can use the installer. These are kept inside a tools package of your agent. For example, in weblogic agent in the workspace, you can see the classes in the tools directory for weblogic 10 agent in the cvs repsoitory at https://opensso.dev.java.net/source/browse/opensso/products/j2eeagents/weblogic/v10/source/com/sun/identity/agents/tools/weblogic/v10/ and these classes do things like accept values from users when they run the agent installer agentadmin and then use these values to set some agent configuration during installation. Each agent may need to ask specific questions os these classes would collect thos specific values and set them for the agent.
*implement some agent classes that use the opensso client sdk classes to interact with the client sdk for this agent. For example, you might need to write some code that gets the redirect url of a form based login request from the specific container version you are using, and each server has slightly different APIs to obtain this info. You can see the classes that were required for the weblogic 10 agent in the opensso cvs repository at https://opensso.dev.java.net/source/browse/opensso/products/j2eeagents/weblogic/v10/source/com/sun/identity/agents/weblogic/v10/ and each agent would need similar classes. For example, each agent needs to override the ServiceResolver.java class of the agentsdk for certain artifacts used by the agentsdk. This allows you to override certain classes in the agentsdk to help with authentication or single sign on.

3-f) opensso\products\j2eeagents\tomcat\v6\extlib\
before building you need to create some jar files that build will depend on and copy them into
opensso\products\j2eeagents\tomcat\v6\extlib\
these include any tomcat jar files that you need
(like maybe tomcat.jar or something that has Servlet classes and any tomcat classes in it)

Note : Please keep a list of third party jar files required for the build to be successful. While setting up nightly for the agent, its required to keep a copy these files to a particular location. Regarding the location, you could contact the dev alias when there is a need to setup the nightly.

PLUS it includes a couple jars from opensso
like:
famclientsdk.jar
which you can download -see README in
opensso\products\j2eeagents for download location.
Just copy into your extlib\
opensso-installtools.jar and opensso-installtools-launcher.jar
which are easily built by going to
opensso\products\installtools\
and running "ant" which will generate the 2 jar files in
a local dist\ directory. Just copy into your extlib\

Please see the README inside opensso\products\j2eeagents if you want lots more details on building a J2EE agent from the workspace(like the appserver or weblogic agents) as you need a couple jar files that you add to that server's workspace extlib\ directory before building. You dont have to build all the jars like famclientsdk (though readme has instructions if you want to) from workspace as this requires a few more steps if you want to do this. I recommend just downloading famclientsdk initially to save time, later can follow intsructions and build whole workspace.

3-g) Try to build
Now from opensso\products\j2eeagents run "ant tomcat_v6"
Things will break if moving code from internal workspace
In theory the build creates a products\j2eeagents\built\
which contains the opensso\products\j2eeagents\built\dist\ with tomcat_v6_agent.zip in it
and also creates a built\ directory
opensso\products\j2eeagents\built\tomcat_v6\ which holds a bunch of temporary scratch files. This is where all the complied code is places plus any copied config files and other stuff that is then jarred up in the dist\
One very useful directory to look at is
opensso\products\j2eeagents\built\tomcat_v6\scratch
and this scracth directory basically mirrors exactly what it looks like for an installed agent, so you can look in this directory and see what files are missing. It should contain same stuff as your internal agent(and similiar to other opensso agents) that is installed/unzipped. When they are the same, you are done.

Some things that will break when moving from internal workspace into opensource... I dont have exact list, but compiler will tell you. Like a couple class names have changed in agentsdk so the tomcat agent code that references them will not compile, a couple in installer too. The good news is that these are compile time erros and say which class is not found. If needed, send an email to us and we can help determine new class name or method name to use.

Some of the changes that are required includes :
1. package name com.sun.identity.agents.tools.configurator have been modified as com.sun.identity.install.tools.configurator
So all references to com.sun.identity.agents.tools.configurator in your files needs to be modifed to com.sun.identity.install.tools.configurator

2. com.sun.identity.agents.tools.util have been modified to com.sun.identity.install.tools.util
So all references to com.sun.identity.agents.tools.util in your files needs to be modified to com.sun.identity.install.tools.util

3. Class AgentUtil is renamed as ConfigUtil. So accordingly, references to AgentUtil needs to be modified to ConfigUtil.

As an overview, the ant files copy stuff(config files plus some jars from extlib\ into scratch\ directory, plus the ant files build the opensso\products\j2eeagents\agentsdk\ code and jar it into agent.jar (this is same for all agents), PLUS it builds your tomcat agent source code.

3-h) later, the tomcat_6 target could be added to the opensso\products\ build files so it gets into nightly builds etc, but first just want to make it work from agent workspace when you run
"ant tomcat_v6" from opensso\products\j2eeagents\

3-i) Use opensource license in source code.
For example, at the top of each source file you need to copy and paste the opensource license text. Just see some of the other files in the workspace for an example.

4) File an Issue as a new Feature for adding a new 2.2 agent
File the issue to add a Tomcat 6 agent on IssueTracker of opensso (insteand of internal bugster) since this IssueTracker of opensso is used for tracking issues for opensource.
Here is an example of issue I filed fo BEA 10 agent https://opensso.dev.java.net/issues/show_bug.cgi?id=731

5) Testing
Eventually QE will take a pass at the agent after you have committed code etc. But first, you are expected to do some developer testing. If there are any unit tests or test suites for your agent, lease run them.
Additionally, you should try out features like installation, try on a couple operating systems like Windows and Solaris, etc.
One key test is to try out the sample application that is part of the agent. You should configure the settings and deploy the sample application, log in as some users and click around the app and see if you get the expected behavior. Maybe try changing a few more agent properties and trying those features.

6)Committing code
For details on opensso development process, see this document on opensso

Basically,

a) you run the "ant cvsdiff"from the opensso\products\ directory
and it creates a directory called C:\workspace\opensso\products\diffs
which contains a "stat" file which has a small list of the modified files plus a ".diffs" file which has the cumulative changes to all source code from cvs diff (you will use info from "stat" file on code review email and can attach the ".diffs" file to code review email, and you can ignore the other files.
For new agents though there are not many diffs except small
changes to build files since mostly it is new code so,
maybe also zip up all the new code and attach the zip to the issue

b) you submit a code review request to mailing list
code-review@opensso.dev.java.net
For an example, see https://opensso.dev.java.net/servlets/ReadMsg?list=code-review&msgNo=1623

c) Incorporate any comments from code review back into your code, and then repeat steps a) and b) until approval

d) then after code review and approval, file a CRT https://opensso.dev.java.net/public/use/builds/crtfinal.html
and after CRT approval you do a cvs commit into 2.2 branch

7) Use the opensso developers mailing list for questions
Also, for coding questions or problems, use the public mailing lists https://opensso.dev.java.net/servlets/ProjectMailingListList
like
dev@opensso.dev.java.net
Its opensource so transparency to the public is a good thing.