Application Configuration

This hands-on exercise will expose users to the new Application Configuration features available in Java CAPS 6 as they relate to a Repository-based CAPS project. In a repository-based CAPS project, all connectivity information is stored in the project EAR file. Any change to the connectivity information requires a rebuild and redeploy of the project. The the new Application Configuration features allow you to externalize the connectivity information. Changes to the connectivity information only requires you to restart your application (you don't have to rebuild and redeploy your CAPS application).

This lab consists of 7 sections -
0. Pre-requisites
1. Import and test the Repository-based CAPS project
2. Extract Application Configuration
3. Import Application Configuration
4. Change a configuration from the Glassfish Admin Console
5. Change a configuration from the Command Line
6. The asadmin Verifier tool

Part 0: Pre-requisites

This lab takes a repository-based project that reads a file using a File eWay and inserts a record into a MySQL database table using the JDBC eWay. The lab then shows how to change connectivity information using the new Application Configuration features.
To do this exercise and be able to import the artifacts, you would need CAPS 6 and MySQL installed. The lab assumes you have 2 databases in MySQL named 'test' and 'prod'. Also, you would need the 'EMP' table to exist in both the databases. Here's the script to create the EMP table.

So, here's the pre-requisites checklist -

1. CAPS 6 GA is installed
2. MySQL is installed
3. Two databases "test" and "prod" are created in MySQL
4. "EMP" table is created in both "test" and "prod" databases. Here's the script to create the EMP table.

Part 1: Import and test the Repository-based CAPS project

1. Start your Repository
2. Start Netbeans
3. Connect to the Repository from Netbeans
4. Import this project. The project export also includes the Environment required for this lab. (Click on Tools --> CAPS Repository --> Import Project, and then point to the CAPS Repo project's zip file)
5. Create a deployment profile
   • Create a DP in the "Deployment" sub-project
   • Call the deployment profile "DP"
   • Select the environment "EnvAppConfig" from the list of environments - You might have to change the MySQL connection parameters in the Environment based on your local MySQL installation.
   • Use the "Automap" option to map the components to the external containers.
6. Build and deploy the project
7. Test the project
   • The input File eWay looks for a file named Insert-Into-MySQL-EMP.txt in C:\temp\AppConfig
   • Copy the input file into C:\temp\AppConfig
   • Once the input file gets picked up, the file should get renamed to Insert-Into-MySQL-EMP.txt.~in
   • Check the "EMP" table in the "test" database. A record should be inserted into the table.
   • If the test fails with an exception message "Caused by: java.sql.SQLException: JDBCADPTR-0042: Failed opening a database session: java.sql.SQLException: Error in allocating a connection. Cause: Class name is wrong or classpath is not set for : com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource" copy the MySQL Driver file mysql-connector-java-5.1.5-bin.jar from <CAPS 6 Home>\netbeans\ide9\modules\ext into <CAPS 6 Home>\appserver\domains\domain1\lib\ext. Restart the server.

Part 2: Extract Application Configuration

1. Copy the project's EAR file into a working directory, say C:\temp\AppConfig
   • You can find the EAR file here - <CAPS6 Install Dir>\.netbeans\caps\builds\<Name of DP>AppConfigDeployment\LogicalHost1\SunJavaSystemApplicationServer1
2. Execute command asadmin extract-caps-application-configuration --capsconfigdir C:\temp\AppConfig\Properties C:\temp\AppConfig\<Repo_Project_File>.ear

   You will either have to change directories to C:\JavaCAPS6\appserver\bin> or add C:\JavaCAPS6\appserver\bin> to your PATH variable before you run the asadmin command.

   • The properties files will be created in directory C:\temp\AppConfig\Properties. If you don't specify the "--capsconfigdir" argument, then the properties files will be created under your current directory.
   • In the specified directory, you will see 2 directories are created - "CM" and "ENV" - the "CM" directory will hold the properties files corresponding to the configurations in the Connectivity Map and the "ENV" directory will hold the properties files corresponding to the configurations in the Environment

Part 3: Import Application Configuration

1. Execute command asadmin import-caps-configuration C:\temp\AppConfig\Properties
   • This will import the Application Configuration properties files into the App Server
   • In the Admin Console, these imported configurations show up under CAPS --> Environment and CM Overrides
   • If you need to delete the imported configurations, you can do that from Resources --> JNDI --> Custom Resources
   • You can now edit the Application Configurations in 2 ways -
     • From the Admin Console
     • By editing the properties files

Part 4: Change a configuration from the Glassfish Admin Console

1. Go to the Admin Console and click on the File Configuration under CAPS --> Environment and CM Overrides --> CM Overrides
2. You should see a page similar to this screenshot
3. Change the name of the input file from Insert-Into-MySQL-EMP.txt to Insert-Into-MySQL-EMP-Changed.txt. Click Save.
4. Now all you have to do for the new configuration to take effect is to Restart your CAPS application - no need to rebuild and redeploy the EAR file.
5. To Restart the CAPS application, open the Admin Console and go to Applications --> Enterprise Applications. Click on the checkbox next to the CAPS application, click on "Disable" to disable the application, then click on "Enable" to enable the application.
6. Notice that the input file with name Insert-Into-MySQL-EMP.txt no longer gets picked up by the File eWay. Rename the input file to Insert-Into-MySQL-EMP-Changed.txt, and notice that the file gets picked up by the File eWay.

Part 5: Change a configuration from the Command Line

1. Edit the properties file corresponding to the MySQL Environment object.
   • This file is called MySQL_Outbound.properties and can be found under C:\TEMP\AppConfig\Properties\ENV\EnvAppConfig\LogicalHost1
2. Edit this file and change "DatabaseName=test" to "DatabaseName=prod". Save the file.
3. Execute command asadmin import-caps-configuration C:\temp\AppConfig\Properties
   • This will re-import the properties files. The existing imported configurations will be over-written.
   • The MySQL database will now be set to "prod", instead of "test". And the Input filename will be rest to Insert-Into-MySQL-EMP.txt
4. Restart the CAPS application by doing disabling it, and then enabling it back.
5. The file eWay will now pick up a file Insert-Into-MySQL-EMP.txt and a record will be inserted into the EMP table in the "prod" database, not the "test" database.

Part 6: The asadmin Verifier tool

1. The asadmin verify command is a tool that introspects a Composite Application or EAR
2. When executed against a Repository-based project's EAR files:
   • The Verifier tool lists all external systems
   • Checks that each external system is defined in the AS
3. Execute command asadmin verify-caps-ee-application-environment C:\temp\AppConfig\<Repo_Project_File>.ear
4. You should see output like

   C:\>asadmin verify-caps-ee-application-environment C:\temp\AppConfig\<Repo_Project_File>.ear
   
   EAR filename:C:\temp\AppConfig\Deployment1AppConfigDeployment.ear
   JNDI Name:capsenv/ENV/EnvAppConfig/LogicalHost1/MySQL_Outbound
   Referenced By:Resource Adapter
   Referencing Class:com.stc.connector.jdbcadapter.base.JDBCResourceAdapter
   Message:Reference resolved successfully
   Status:OK
   
   ...
   ...
   
   EAR filename:C:\temp\AppConfig\Deployment1AppConfigDeployment.ear
   JNDI Name:capsenv/CM/AppConfig | Deployment/CMap1_jcdInsertIntoMySQL1/File1
   Referenced By:File1_CMap1_jcdInsertIntoMySQL1
   Referencing Class:STC_MDB__File1_CMap1_jcdInsertIntoMySQL1
   Message:Reference resolved successfully
   Status:OK
   
   Command verify-caps-ee-application-environment executed successfully.
   

5. Now, go back to your Admin Console and navigate to the "Custom Resources" section (Resources --> JNDI --> Custom Resources). This section lists the environment objects imported in the AppServer and allows you to Enable/Disable/Delete the environment objects.
6. Delete one or more of the environment objects that show up. See screenshot below -
   
   
   
   
7. Execute the asadmin verify command again. Compare the result with the last time you executed the verify command.

   C:\>asadmin verify-caps-ee-application-environment C:\temp\AppConfig\<Repo_Project_File>.ear
   
   EAR filename:C:\temp\AppConfig\Deployment1AppConfigDeployment.ear
   JNDI Name:capsenv/ENV/EnvAppConfig/LogicalHost1/MySQL_Outbound
   Referenced By:Resource Adapter
   Referencing Class:com.stc.connector.jdbcadapter.base.JDBCResourceAdapter
   Message:Reference resolved successfully
   Status:OK
   
   ...
   ...
   
   EAR filename:C:\temp\AppConfig\Deployment1AppConfigDeployment.ear
   JNDI Name:capsenv/CM/AppConfig | Deployment/CMap1_jcdInsertIntoMySQL1/File1
   Referenced By:File1_CMap1_jcdInsertIntoMySQL1
   Referencing Class:STC_MDB__File1_CMap1_jcdInsertIntoMySQL1
   Message:Cannot resolve reference
   Status:WARNING
   
   Command verify-caps-ee-application-environment executed successfully.
   

8. Notice these 2 lines in the output -

   Message:Cannot resolve reference
   Status:WARNING 
   

9. The output of the asadmin verify command highlights to the user that one of the environment objects that exists in the EAR file, does not exist in the Application Server, and that the user should create the resource in the AppServer if required. This feature can come in handy when dealing with several EAR files that have several different environment objects each.

Appendix 1:

Gotchas Not all eWays support all the Application Configuration features HTTP eWay support App Config in outbound mode only Siebel eWay support App Config in outbound mode only PeopleSoft eWay support App Config in outbound mode only Scheduler eWay does not support App Config WebServices eWay does not support App Config

Appendix 2:

A note about passwords When you export application configurations for eWays, the property files will have encrypted password. If you want to change them simply over write the encrypted password with clear text password and save the file first, then use the application configuration import facility to import the changed configuration back to the runtime, during import the tool will do the following: Change the configurations in the run time system appropriately. Re-encrypt password and replace and clear password with encrypted password in the property file

Questions and Answers

1. Can Application Configuration features be used with JBI Components (specifically if the JBI components use Environment Variables)?

   Answer

2. Does the verifier command do a syntax check on the properties file? If user makes a mistake in editing a properties file, and then runs the import command, the import succeeds. Is it possible to add a validation to the verifier command?

   Answer

3. The Verifier command only checks the EAR file against the Environment Objects in the App Server? Can we have a variation of the verifier command that can verify against the Properties files that have been extracted from the EAR file?

   Answer

You can watch a screencast of the above here (screencast only - no controls, no progress bar), and download it from here (screencast with controls and progress bar)