OSGi colors sample application

The colors sample application demonstrates two of the key dynamic abilities of OSGi Applications for WebSphere® Application server: how to administratively update deployed applications in a modular fashion, at the bundle level, and how to extend running applications, as your business requirements change, without changing the underlying application.

Before you begin

Extract the contents of the colorsSample.zip compressed file to your local drive.

About this task

The colors sample application consists of the following components:

com.ibm.samples.websphere.osgi.colors.eba, the core colors sample enterprise bundle archive.
com.ibm.samples.websphere.osgi.colors.blender_1.0.1.jar, an updated version of one of the bundles inside the colors sample application.
com.ibm.samples.websphere.osgi.colors.brightness.extension.cba, a composite bundle archive that can be used to extend the colors sample application.

The bundles in com.ibm.samples.websphere.osgi.colors.eba are divided into the following functional areas:

com.ibm.samples.websphere.osgi.colors.api.jar, which contains the API for the whole sample.
com.ibm.samples.websphere.osgi.colors.blender.jar, which blends the provided colors.
com.ibm.samples.websphere.osgi.colors.provider.red.jar, which provides "red".
com.ibm.samples.websphere.osgi.colors.provider.green.jar, which provides "green'.
com.ibm.samples.websphere.osgi.colors.provider.blue.jar, which provides "blue".
com.ibm.samples.websphere.osgi.colors.web.jar, which is the web front end to the color blending application.

The bundles in com.ibm.samples.websphere.osgi.colors.brightness.extension.cba are divided into the following functional areas:

com.ibm.samples.websphere.osgi.colors.brightness.blueprint.jar, which contains a BrightnessDelta bean that implements the BrightnessService in the colors API.
com.ibm.samples.websphere.osgi.colors.brightness.web.jar, which is the web front end to the colors brightness extension.

You can use scripts to install or uninstall com.ibm.samples.websphere.osgi.colors.eba, the core colors sample application. You can then use the com.ibm.samples.websphere.osgi.colors.blender_1.0.1.jar file to update the sample, and the com.ibm.samples.websphere.osgi.colors.brightness.extension.cba file to extend the sample. After running the uninstall script, the update JAR file or extension CBA file can then be removed from the internal bundle repository if they are no longer required.

Procedure

Install and view the colors sample.

You can install the colors sample by running the colorsSampleInstall.py script, which is provided in the scripts directory of the colorsSample.zip compressed file.

In the following steps, you must substitute your own values for the variables app_server_root, profileName, serverName, and nodeName.

Run the command from the directory to which you extracted the colorsSample.zip compressed file.
1. Run the colorsSampleInstall.py script.
  On UNIX platforms:
```
app_server_root/profiles/profileName/bin/wsadmin.sh
-f scripts/colorsSampleInstall.py serverName
nodeName installableApps/com.ibm.samples.websphere.osgi.colors.eba 
```
  On Windows platforms:
```
app_server_root/profiles/profileName/bin/wsadmin.bat 
-f scripts/colorsSampleInstall.py serverName
nodeName installableApps/com.ibm.samples.websphere.osgi.colors.eba
```
Use your browser to navigate to http://server:port/context_root/ShowColors; by default, the URL is http://localhost:9080/colors/ShowColors. The show colors screen is displayed.

The following illustration shows the correctly running sample:

The displayed values are the red, green, and blue color settings, and the color of the text reflects those settings.
Extend the colors sample
1. Use the administrative console to add the com.ibm.samples.websphere.osgi.colors.brightness.extension.cba file to the internal bundle repository.
  1. Click Environment > OSGi bundle repositories > Internal bundle repository
  2. Click New.
  3. Click Browse and navigate to the uncompressed_sample_dir/installableApps directory, where uncompressed_sample_dir is the directory to which you extracted the colorsSample.zip compressed file.
  4. Select the com.ibm.samples.websphere.osgi.colors.brightness.extension.cba file, then click Open.
  5. Click OK, then click Save to save your changes to the master configuration.
2. Use the administrative console to manage extensions for the composition unit.
  1. Click Applications > Application Types > Business-level applications.
  2. Click Colors Sample.
  3. Click the deployed asset com.ibm.samples.websphere.osgi.colors_0001.eba.
  4. Click Extensions for this composition unit, then click Add.
  5. Select the check box alongside com.ibm.samples.websphere.osgi.colors.brightness.ext, then click Add.
  6. Click Save to save your changes to the master configuration.
3. Use the administrative console to update the business-level application to the latest deployment.
  1. Click Applications > Application Types > Business-level applications.
  2. Click Colors Sample.
  3. Click the deployed asset com.ibm.samples.websphere.osgi.colors_0001.eba.
  4. Click Update to latest deployment. Note that the Deployed Version property of com.ibm.samples.websphere.osgi.colors.brightness.ext is set to Not deployed, and the New Version is set to 1.0.0.
  5. Click OK.
  6. On the Context root for web modules page, accept the default values by clicking Next.
  7. On the Virtual hosts for web modules page, accept the default values by clicking Next.
  8. On the Web module message destination references page, accept the default values by clicking Finish.
  9. Click Save to save your changes to the master configuration. The colors sample has now been extended.
Use your browser to navigate again to http://server:port/context_root/ShowColors; by default, the URL is http://localhost:9080/colors/ShowColors. You will see that the default brightness increment of 100 has been applied to the colors. The background color changes to black; this is because when the text reaches a certain brightness level, the application blackens the background so that the displayed text remains visible.

The following illustration shows the correctly running sample with the extension:

Use your browser to navigate to http://server:port/context_root_for_extension_web_module/; by default the URL is http://localhost:9080/brightness/. From here you can submit a new brightness increment.
Update the colors sample
1. Use the administrative console to add the com.ibm.samples.websphere.osgi.colors.blender_1.0.1.jar file to the internal bundle repository.
  1. Click Environment > OSGi bundle repositories > Internal bundle repository.
  2. Click New.
  3. Click Browse and navigate to the uncompressed_sample_dir/installableApps directory, where uncompressed_sample_dir is the directory to which you extracted the colorsSample.zip compressed file.
  4. Select the com.ibm.samples.websphere.osgi.colors.blender_1.0.1 file, then click Open.
  5. Click OK, then click Save to save your changes to the master configuration.
2. Use the administrative console to update bundle versions in the colors sample application.
  1. Click Applications > Application Types > Assets.
  2. Click com.ibm.samples.websphere.osgi.colors.eba.
  3. Click Update bundle versions in this application.
  4. By default, the highest available version of each bundle is selected. Click Preview and you will see that the New Version property of com.ibm.samples.websphere.osgi.colors.blender is set to 1.0.1.
  5. Click Create, then click Save to save your changes to the master configuration.
3. Use the administrative console to update the business-level application to the latest deployment.
  1. Click Applications > Application Types > Business-level applications.
  2. Click Colors Sample.
  3. Click the deployed asset com.ibm.samples.websphere.osgi.colors_0001.eba.
  4. Click Update to latest deployment and you will see that the New Version property of com.ibm.samples.websphere.osgi.colors.blender is set to 1.0.1.
  5. Click OK, then click Save to save your changes to the master configuration. The colors sample has now been updated.
Use your browser to navigate again to http://server:port/context_root/ShowColors; by default, the URL is http://localhost:9080/colors/ShowColors. You will notice that green is now zero. This is because com.ibm.samples.websphere.osgi.colors.blender has been updated to remove any green that is provided. You will also notice that following the update, and the extension, the demonstration counters, invocations since last servlet restart and invocations since last bundle restart, continued to increment.

The following illustration shows the correctly running sample with the extension and the update:
Uninstall the colors sample

You can uninstall the colors sample by running the colorsSampleUninstall.py script, which is provided in the scripts directory of the colorsSample.zip compressed archive file.

Run the command from the directory to which you extracted the colorsSample.zip compressed file.
1. Run the colorsSampleUninstall.py script.
  On UNIX platforms:
```
app_server_root/profiles/profileName/bin/wsadmin.sh
     -f scripts/colorsSampleUninstall.py
```
  On Windows platforms:
```
app_server_root\profiles\profileName\bin\wsadmin.bat 
-f scripts\colorsSampleUninstall.py
```
2. If you have installed com.ibm.samples.websphere.osgi.colors.blender_1.0.1.jar or com.ibm.samples.websphere.osgi.colors.brightness.extension.cba, you must manually remove them from the internal bundle repository.