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.
- 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
- Use the administrative console to add the com.ibm.samples.websphere.osgi.colors.brightness.extension.cba file
to the internal bundle repository.
- Click
- Click New.
- 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.
- Select the com.ibm.samples.websphere.osgi.colors.brightness.extension.cba file,
then click Open.
- Click OK, then click Save to
save your changes to the master configuration.
- Use the administrative console to manage extensions
for the composition unit.
- Click .
- Click Colors Sample.
- Click the deployed asset com.ibm.samples.websphere.osgi.colors_0001.eba.
- Click Extensions for this composition unit,
then click Add.
- Select the check box alongside com.ibm.samples.websphere.osgi.colors.brightness.ext,
then click Add.
- Click Save to save your changes to the
master configuration.
- Use the administrative console to update the business-level
application to the latest deployment.
- Click .
- Click Colors Sample.
- Click the deployed asset com.ibm.samples.websphere.osgi.colors_0001.eba.
- 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.
- Click OK.
- On the Context root for web modules page,
accept the default values by clicking Next.
- On the Virtual hosts for web modules page,
accept the default values by clicking Next.
- On the Web module message destination references page,
accept the default values by clicking Finish.
- 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
- Use the administrative console to add the com.ibm.samples.websphere.osgi.colors.blender_1.0.1.jar file
to the internal bundle repository.
- Click .
- Click New.
- 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.
- Select the com.ibm.samples.websphere.osgi.colors.blender_1.0.1 file,
then click Open.
- Click OK, then click Save to
save your changes to the master configuration.
- Use the administrative console to update bundle versions
in the colors sample application.
- Click .
- Click com.ibm.samples.websphere.osgi.colors.eba.
- Click Update bundle versions in this application.
- 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.
- Click Create, then click Save to
save your changes to the master configuration.
- Use the administrative console to update the business-level
application to the latest deployment.
- Click .
- Click Colors Sample.
- Click the deployed asset com.ibm.samples.websphere.osgi.colors_0001.eba.
- 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.
- 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.
- 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
- 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.