Child pages
  • How to convert an existing AM service from schema xml based service to config annotation API based service
Skip to end of metadata
Go to start of metadata

This article is essentially a cheat sheet to outline the steps involved in converting an existing schema XML based AM service to config annotation API based service. 

Broadly the conversion of a given service can be thought to have two parts.

  1. Create an Interface to represent the configuration details of in schema file that is being replaced  
    1. Create a new service interface extending the ServiceComponentConfig interface to represent the service.
    2. If the service that is being converted has realm configuration then the service interface must extend the RealmConfiguration interface. The service interface should encompass a subinterface with the realm scope with methods on this interface annotated with Attribute annotation to represent the configuration attributes in the XML schema.
    3. If the service that is being converted has global configuration then the service interface must extend the GlobalConfiguration interface. The service interface should encompass a subinterface with the global scope with methods on this interface annotated with Attribute annotation to represent the configuration attributes in the XML schema.
  2. Use the newly created service interface to look up the service configuration and adding listeners to take appropriate action when the config/schema changes. 
     

Useful classes to know for debugging 

org.forgerock.openam.sm.annotations.SchemaBuilder
org.forgerock.openam.sm.annotations.InstanceBuilder
org.forgerock.openam.sm.annotations.AnnotatedServiceFactory

Useful Tip:

Add the system property org.forgerock.log.genereated.schema to log the XML that is generated from the newly added service interface.
The XML would get written into the install log during installation.

The easiest and quickest way to understand and get started is to look at a PR where a simple service is converted from XML based to config API based service.
For example https://stash.forgerock.org/projects/OPENAM/repos/openam/pull-requests/10144/overview

Step-by-step guide

  1. Create a new service interface.
  2. Add a file named org.forgerock.am.config.ServiceComponentConfig in META-INF/services. This file must contain the fully qualified name of the new service interface. AM relies on these files to load the annotated services on AM startup.
  3. Remove the schema file name entry from the serviceName.properties file
  4. Delete the XML schema file.
  5. Use the newly created interface to access the service config. This involves locating and removing the usage of ServiceConfigManager#getOrganizationConfig, ServiceConfigManager#getGlobalConfig to access the realm config and global config of the service respectively.