|
1 | 1 | # cics-java-osgi-ds |
2 | 2 | Demonstration of Declarative Services (DS) in OSGi JVM servers |
3 | 3 |
|
| 4 | +## Preface |
| 5 | +This example shows how OSGi Declarative Services (DS) can be used in OSGi JVM servers to construct modular applications, with the ability to change implementations without loss of service. |
| 6 | + |
| 7 | +There are a number of projects in this simple sample (4 OSGi projects, each a corresponding CICS bundle project). However, even a complex application may still fit into this structure, depending on architecture. |
| 8 | + |
| 9 | +Below is a simple diagram which explains the relationships between these projects: |
| 10 | + |
| 11 | +``` |
| 12 | + Implementation +-----------+ |
| 13 | + /------------------| In memory | |
| 14 | ++----------+ +-------------------+ / +-----------+ |
| 15 | +| | Injection | |<--/ |
| 16 | +| CICS App |<------------| Storage Interface | |
| 17 | +| | | |<--\ |
| 18 | ++----------+ +-------------------+ \ +-----------+ |
| 19 | + \------------------| TSQ | |
| 20 | + Implementation +-----------+ |
| 21 | +``` |
| 22 | + |
| 23 | +The *CICS App* is the OSGi bundle which contains the CICS main class. It uses the interface provided by the *Storage Interface* to put data into storage and retrieve data from storage. |
| 24 | + |
| 25 | +In this example, we have two separate implementations of the storage service. Version 1.0.0 is a simple in-memory storage system, which uses Java objects to store data. |
| 26 | + |
| 27 | +The second implementation, version 1.1.0, uses a CICS TSQ to store data, using the JCICS APIs. |
| 28 | + |
| 29 | +In our example we follow the scenario that we have the base application running using the in-memory storage service and we now want to upgrade to the new TSQ storage service. |
| 30 | + |
| 31 | +When we first install the new bundle, the TSQ storage service will activate, but the CICS App will remain bound to the in-memory implementation. We can then disable the in-memory implementation. At which point OSGi declarative services will bind the new TSQ service and unbind the in-memory service (in that order). This means the CICS App is never left without a working implementation and therefore avoiding loss of service. |
| 32 | + |
4 | 33 | ## Supporting Files |
5 | | -* [com.ibm.cicsdev.osgi.ds_1.0.0](projects/com.ibm.cicsdev.osgi.ds_1.0.0) - OSGi interfaces |
6 | | -* [com.ibm.cicsdev.osgi.ds.bundle_1.0.0](projects/com.ibm.cicsdev.osgi.ds.bundle_1.0.0) - CICS Bundle for the OSGi interfaces |
7 | | -* [com.ibm.cicsdev.osgi.ds.app_1.0.0](projects/com.ibm.cicsdev.osgi.ds.app_1.0.0) - CICS application entry point |
8 | | -* [com.ibm.cicsdev.osgi.ds.app.bundle_1.0.0](projects/com.ibm.cicsdev.osgi.ds.app.bundle_1.0.0) - CICS Bundle containing the application, program and transaction. |
9 | | -* [com.ibm.cicsdev.osgi.ds.tsq_1.0.0](projects/com.ibm.cicsdev.osgi.ds.tsq_1.0.0) - In-memory implementation |
10 | | -* [com.ibm.cicsdev.osgi.ds.tsq.bundle_1.0.0](projects/com.ibm.cicsdev.osgi.ds.tsq.bundle_1.0.0) - CICS Bundle for the base in-memory implementation |
11 | | -* [com.ibm.cicsdev.osgi.ds.tsq_1.0.1](projects/com.ibm.cicsdev.osgi.ds.tsq_1.0.1) - TSQ implementation |
12 | | -* [com.ibm.cicsdev.osgi.ds.tsq.bundle_1.0.1](projects/com.ibm.cicsdev.osgi.ds.tsq.bundle_1.0.1) - CICS Bundle for the TSQ implementation |
| 34 | +* [com.ibm.cicsdev.osgi.ds.cicsapp_1.0.0](projects/com.ibm.cicsdev.osgi.ds.cicsapp_1.0.0) - CICS application entry point |
| 35 | +* [com.ibm.cicsdev.osgi.ds.cicsapp.bundle_1.0.0](projects/com.ibm.cicsdev.osgi.ds.cicsapp.bundle_1.0.0) - CICS Bundle containing the application, program and transaction definitions. |
| 36 | +* [com.ibm.cicsdev.osgi.ds.storage_1.0.0](projects/com.ibm.cicsdev.osgi.ds.storage_1.0.0) - Interfaces for the storage service |
| 37 | +* [com.ibm.cicsdev.osgi.ds.storage.bundle_1.0.0](projects/com.ibm.cicsdev.osgi.ds.storage.bundle_1.0.0) - CICS Bundle for the storage service interface |
| 38 | +* [com.ibm.cicsdev.osgi.ds.storage.impl_1.0.0](projects/com.ibm.cicsdev.osgi.ds.storage.impl_1.0.0) - In-memory implementation of the storage service |
| 39 | +* [com.ibm.cicsdev.osgi.ds.storage.impl.bundle_1.0.0](projects/com.ibm.cicsdev.osgi.ds.storage.impl.bundle_1.0.0) - CICS Bundle for the base in-memory implementation |
| 40 | +* [com.ibm.cicsdev.osgi.ds.storage.impl_1.1.0](projects/com.ibm.cicsdev.osgi.ds.storage.impl_1.1.0) - TSQ implementation of the storage service |
| 41 | +* [com.ibm.cicsdev.osgi.ds.storage.impl.bundle_1.1.0](projects/com.ibm.cicsdev.osgi.ds.storage.impl.bundle_1.1.0) - CICS Bundle for the TSQ implementation |
13 | 42 |
|
14 | 43 | ## Usage |
15 | 44 | 1. Deploy all found bundle projects to z/FS |
16 | 45 | 2. Create an OSGi JVM server with the name `DFHOSGI`. |
17 | | -3. Define CICS bundles for these bundle projects. [Table 1](#table-1) shows the mapping of bundle to bundle name used. |
18 | | -4. Install `DS `, `DS.APP ` and `DS.TSQ10`. |
| 46 | +3. Create CICS bundle definitions for these bundle projects. [Table 1](#table-1) shows the mapping of bundle to bundle name used. |
| 47 | +4. Install the bundles: `DS `, `DS-APP ` and `DS-IMP10`. |
19 | 48 | 5. Run the transaction `DSTS PUT INMEM`, this should display the message `Created entry 1` |
20 | 49 | 6. Run the transaction `DSTS GET 1`, this should display the message `INMEM`, which confirms the data was stored correctly in-memory |
21 | | -7. Install the bundle `DS.TSQ11`. |
22 | | -8. Disable the bundle `DS.TSQ10`. |
| 50 | +7. Install the bundle `DS-IMP11`. |
| 51 | +8. Disable the bundle `DS-IMP10`. |
23 | 52 | 9. Run the transaction `DSTS GET 1`, this should ABEND because the entry was not found in the TSQ. |
24 | 53 | 10. Run the transaction `DSTS PUT TSQ`, this should display the message `Created entry 1` |
25 | | -10. Run the transaction `DSTS GET 1`, this should display the message `TSQ`, which confirms the data was stored correctly in the TSQ (confirm by browsing on the TSQ `TSQS`, e.g. `CEBR TSQS`). |
26 | | -11. The standard out (STDOUT) file for the JVM server should display messages which indicate that the in-memory service (version 1.0.0) was first bound. Then later unbound when the bundle was disabled. Then that the TSQ service (1.0.1) was bound in it's place. |
| 54 | +10. Run the transaction `DSTS GET 1`, this should display the message `TSQ`, which confirms the data was stored correctly in the TSQ (confirm by browsing on the TSQ `TSQS`, using the `CEBR` transaction for example). |
| 55 | +11. The standard out (STDOUT) file for the JVM server should display messages which indicate that the in-memory service (version 1.0.0) was first bound. Then later unbound when the bundle was disabled. Then that the TSQ service (1.1.0) was bound in it's place. |
27 | 56 |
|
28 | 57 |
|
29 | 58 | ### Table 1 |
30 | 59 |
|
31 | 60 | | CICS Bundle Name | Bundle Project | |
32 | 61 | | ---------------- | ---------------------------------------- | |
33 | 62 | | `DS ` | com.ibm.cicsdev.osgi.ds.bundle_1.0.0 | |
34 | | -| `DS.APP ` | com.ibm.cicsdev.osgi.ds.app.bundle_1.0.0 | |
35 | | -| `DS.TSQ10` | com.ibm.cicsdev.osgi.ds.tsq.bundle_1.0.0 | |
36 | | -| `DS.TSQ11` | com.ibm.cicsdev.osgi.ds.tsq.bundle_1.0.1 | |
| 63 | +| `DS-APP ` | com.ibm.cicsdev.osgi.ds.app.bundle_1.0.0 | |
| 64 | +| `DS-IMP10` | com.ibm.cicsdev.osgi.ds.tsq.bundle_1.0.0 | |
| 65 | +| `DS-IMP11` | com.ibm.cicsdev.osgi.ds.tsq.bundle_1.0.1 | |
37 | 66 |
|
0 commit comments