Levels of support

We differentiate two levels of support for APIs:

To mark an API supported

On latest version of AM this can be done by marking the relevant package/class/etc with the @Supported or @Evolving annotations. There are four annotation types available:

For versions prior to 7.0.0, there are four custom Javadoc tags that can be used:

The @SupportedAll and @EvolvingAll annotations can be used on classes or interfaces, and mark that every single component (field/constructor/method/class) of that class/interface should be part of the public Javadoc.

If you don't want to add a whole class to the public Javadoc, then add the @Supported or @Evolving annotation at the class level and use @Supported or @Evolving annotations to mark components one-by-one.

Any class that contains supported/evolving functionality must be marked public. Private and package-private classes are not included in the javadoc.

Note that methods and fields within these classes may still be generified when appropriate.

In case there is a new package involved for a new supported API, then:

When working on < AM 7.0.0 versions, use the relevant JavaDoc taglets as opposed to the annotations.

Building the Javadoc

The product Javadoc can be built so you can see easily what is already supported API:

mvn clean source:jar javadoc:jar@attach-javadocs -pl openam-server-only -am -P\!xui,forgerock-release

The following might be an example of how to both build the Javadoc and then view it in your default browser:

mvn clean source:jar javadoc:jar@attach-javadocs -pl openam-server-only -am -P\!xui,forgerock-release
open openam-server-only/target/site/apidocs/index.html

The built Javadoc will also include all supported commons projects that might need to be used in order to implement an extension to AM - these are included automatically by including all modules that are dependencies of the openam-server-only module.

When to add Supported API

The decision to include supported API on classes should be based on whether customers need the class in order to extend or subclass product code.

"As a rule of thumb, try implementing a plugin or extension to the system. If you find you need a product class to do this, then it should be supported API"

When ever a supported class changes, we need to notify customers via a release notes change to make them aware that they might need to rebuild their custom plugins and related code.

Newly created APIs that are expected to be used in extensions should initially be marked as evolving, so that if necessary changes can be made as the new API stabilises in subsequent releases.

How to change Supported API classes

If you find you need to change a supported API class, make the change as normal.

In addition, raise a JIRA ticket with the following fields:

An example of a ticket raised for this is AME-15439.