Contents


Simplify complex code with OSGi services in Decision Server Insights rules

Integrate Open Service Gateway initiative services into IBM Operational Decision Manager

Comments

IBM ODM Decision Server Insights is a highly available event-driven solution for transactional workloads that combines change detection capabilities with decision making and business analytics. Decision Server Insights has a very rich and intuitive rule language that allows users to write their business logic in natural language. The ability to write rules using a natural language allows nontechnical users to directly influence and control the situations that represent opportunities or risks within the business.

The rule language provides a lot of flexibility for working with and analyzing data and then deciding upon a course of action. However, there are times when it's necessary to perform more complex data manipulations, or to leverage enterprise systems or existing web services. These types of operations often involve complex Java™ code that must be concealed from nontechnical users. The challenge is then to make these extended capabilities part of the natural rules language that users are comfortable with.

Decision Server Insights allows you to solve this problem through the use of an OSGi service and a business object model (BOM). At a high level, you can think of the OSGi service as the encapsulation component for the Java logic. The BOM provides the rules language with a business user-friendly interface to that logic. After these technical artifacts are created, nontechnical users can use the user-friendly representation of the service in business rules.

This tutorial walks you through the process of creating an OSGi service and the corresponding business object model. It also shows you how to use that service in a business rule and how to make the service an integral part of your Decision Server Insights solution.

You should have a basic understanding of IBM ODM Decision Server Insights, including how a Decision Server Insights solution is created and structured. For more information about Decision Server Insights, see the Operational Decision Manager 8.7 documentation on IBM Knowledge Center. This tutorial assumes that you are familiar with Java and the Eclipse IDE, and more obvious steps in the process are not described in detail. You don't need to know OSGi to effectively follow the steps in this tutorial, but readers who are skilled in OSGi will more easily understand some sections.

This tutorial shows a very simple service to guide you through all the necessary steps, from the creation of the OSGi service to its incorporation into the solution. The service simply calculates the age of a person given that person's date of birth. The date of birth is expressed in terms of year, month and the day of the month, all of which have an integer representation.

You complete the following tasks in this tutorial:

  • Create an OSGi bundle project.
  • Create the service interface and its implementation.
  • Create a business object model for the service and verbalize it in a way that is appropriate for business users.
  • Create a Decision Server Insights solution.
  • Create a rule agent with a rule that consumes the OSGi Service.
  • Configure the project dependencies and export the solution.
  • Deploy and run the solution.
  • Use a test client to test the service and verify the results.

All the artifacts and code described in this tutorial are available for download. After you complete the tutorial, you can download the sample code from the Downloads section to compare your work. From the Download section of this tutorial, download the code_sample.zip and extract the files.

Create the OSGi bundle project

Complete the following steps in your Eclipse environment to create an OSGi bundle project, which will contain the service API and the service implementation:

  1. Ensure that you have the IBM WebSphere® Application Server Developer Tools for Eclipse feature installed in your Eclipse Environment. If this feature is not yet installed in your environment, you can click Modify in the IBM Installation Manager for Decision Server Insights and select WebSphere Application Server Development Tools. Then make sure to follow instructions in Installing Decision Server Insights in an existing Eclipse environment in the product documentation on IBM Knowledge Center.
  2. Click File > New and open the OSGi Bundle Project wizard, as shown in Figure 1.
    Figure 1. The OSGi Bundle Project wizard
  3. On the first window of the wizard, enter a name for the project. As shown in Figure 2, select Generate blueprint file and clear Add bundle to application.
    Figure 2. OSGi bundle project configuration
  4. In the next window, ensure that the Bundle root property is clear, as shown in Figure 3. This configuration results in the META-INF and OSGI-INF folders being placed at the root of the OSGi bundle project.
    Figure 3. Bundle settings with no bundle root value
  5. Click Finish to complete the wizard.
  6. Create the Java packages for the service interfaces and for the service implementations. The example in this tutorial creates the com.ibm.osgiservice.example.api package for the interface and the com.ibm.osgiservice.example.impl package for the implementation of the service.
  7. Create the interface and the implementation class. The example service in this tutorial, DateUtilService, calculates the number of years that have elapsed since the date that is given as input to the present moment. The tutorial example uses three parameters as input to the service: year, month and day. The example also uses the org.threeten.bp.LocalDate class in the method implementation because it is a more appropriate format for describing dates of birth and because you can use the org.threeten.bp.Period class to compute the number of years between two local dates. The code for both the interface and the implementation of the service is shown in the following example:

    Interface

    package com.ibm.osgiservice.example.api;
    public interface DateUtilService { /** * Given the year, month and day representing an input date * return the number of years elapsed since that date */ public int ageFromDate(int year, int month, int day ); }

    Implementation

    package com.ibm.osgiservice.example.impl;
    import org.threeten.bp.LocalDate;
    import org.threeten.bp.Period;
    import com.ibm.osgiservice.example.api.DateUtilService;
    
    public class DateUtilServiceImpl implements DateUtilService {
    
    	public DateUtilServiceImpl() {
    }
    
    	//@Override
    	public int ageFromDate(int year, int month, int day ) {		
    		LocalDate localDate = LocalDate.of(year, month, day);
    		Period p = Period.between( localDate, LocalDate.now());
    		return p.getYears();		
    }
    }
  8. Double-click the MANIFEST.MF file, which is typically in the META-INF directory in the OSGi bundle, to open the manifest editor and set the project dependencies. The tutorial example shows a dependency on the org.threeten.bp package, as shown in Figure 4.
    Figure 4. Project dependencies in the manifest editor
  9. Click the Build tab and configure the build properties, as shown in Figure 5. Make sure that Custom Build is not selected.
    Figure 5. Manifest build properties
  10. Click the Runtime tab and add the Java package that you want to export. This is the package where you have created the service interface, as shown in Figure 6.
    Figure 6. Exported API package for the service
  11. Close the manifest editor and double-click the blueprint.xml file to open the blueprint XML editor. From the Design tab, click Add to create a service item, as shown in Figure 7.
    Figure 7. Adding a service item to the blueprint
  12. In the next window, enter the service interface and create an implementation bean definition, as shown in Figure 8.
    Figure 8. Provide the service interface and implementation bean.

    Switch to the Source tab, and you should see a service and bean definition similar to the following example:

    <?xml version="1.0" encoding="UTF-8"?>
    <blueprint xmlns="http://www.osgi.org/xmlns/blueprint/v1.0.0">	
    	<bean id="DateUtilServiceImplBean"
    		class="com.ibm.osgiservice.example.impl.DateUtilServiceImpl" />
    	<service id="DateUtilService" ref="DateUtilServiceImplBean" interface=
    "com.ibm.osgiservice.example.api.DateUtilService"></service>
    </blueprint>

    The OSGi service is now complete. The next step creates a rule project that contains the business object model for the service.

Create the business object model project

Now you create a rule project that contains the business object model (BOM) for the OSGi service executable model (XOM). The BOM describes the service interface an enables it to be used in the rules language. In addition, it defines the verbalization that is used to refer to the service in a business user-friendly way. Complete the following steps to create and configure the service BOM:

  1. Click File > New and open the Rule Project wizard, as shown in Figure 9.
    Figure 9. Rule Project wizard
  2. Give the project a name (for example, service_osgi_bom) and click Next until you get to the XOM settings page. Make sure that you reference the OSGi project that you created in the previous steps (for example, service_osgi), as shown in Figure 10.
    Figure 10. Selecting the OSGi bundle project on the Rule Project XOM Settings window
  3. Click Finish to create the project.
  4. To create a BOM entry in the new project, click File > New and open the BOM Entry wizard, as shown in Figure 11.
    Figure 11. BOM Entry wizard
  5. Click Next and browse to the OSGi XOM. Select the package that contains the service interface, as shown in Figure 12.
    Figure 12. Service package selected on the Create a BOM entry from an XOM window
  6. Click Finish to create the BOM entry.
  7. Open the BOM editor on model.bom, click the Class tab, and navigate to the DateUtilService class.
  8. Add a custom property called OSGi.service that points to the service interface, as shown in Figure 13. Note that character case must match.
    Figure 13. Adding the OSGi.service custom property
  9. Double-click ageFromDate(int,int,int) and click the Member tab. Then select Static to make this method static, as shown in Figure 14.
    Figure 14. The static service method
  10. Change the verbalization to something that is meaningful to the business user, as shown in Figure 15.
    Figure 15. Verbalization
  11. Finally, edit the properties of the BOM project and set the rule engine to the decision engine, as shown in Figure 16.
    Figure 16. Selecting the decision engine

Create a Decision Server Insights solution to consume the OSGi service

Now create a Decision Server Insights solution to consume the service. It's outside of the scope of this tutorial to elaborate on how to develop Decision Server Insights solutions. If you do not have prior experience developing solutions, see the Operational Decision Manager 8.7 documentation on IBM Knowledge Center.

A Decision Server Insights solution is typically made up of a business model and at least one of three agent types: rule agents, Java agents and predictive scoring agents. In the example in this tutorial, the solution that consumes the OSGi service has a rule agent with a rule that references the service. For this reason the rule agent project must reference the OSGi service BOM, as shown in Figure 17.

Figure 17. Project references from the rule agent to the service BOM.

The business model in the example is very simple, as shown in Figure 18. Notice how date of birth is modeled as a concept with three int fields (year, month, and day).

Figure 18. Simple business model for the solution
  1. You can now create a simple rule that consumes the service, as shown in Figure 19. You can use the context help to find the age from verbalization of the OSGi service and to provide the required parameters without having to be aware of the Java implementation.
    Figure 19. Simple rule that references an OSGi service
  2. At this stage you have all that you need to test the invocation of the service from the business rule, but you still must export and deploy your solution. Before you export the solution, check that the solution project references the OSGi service project (called service_osgi in this example), as shown in Figure 20.
    Figure 20. The solution project that references the OSGi project
  3. After you export and deploy your solution, you can test the new OSGi service with a simple test class like the following example:
    public class TestOSGiService {
    	TestDriver client = null;
    
    	@Before
    	public void setUp() throws Exception {
    		client = new TestDriver();
    		client.connect("service_consumer_sol");
    }
                
    	@After
    	public void tearDown() throws Exception {
    		client.disconnect();
    }
    
    	@Test
    	public void test() throws Exception{		
    createEntities();
    
    		Thread.sleep(10000);
    sendEvents(); 
    }
    	private void createEntities() throws Exception {
    		Customer customer = client.getConceptFactory
    							(ConceptFactory.class).createCustomer("111");
    		customer.setName("Mickey Mouse");
    		BirthDate dob=new com.ibm.service.comsumer.impl.BirthDate();
    dob.setYear(1928);
    dob.setMonth(5);
    dob.setDay(15);
    customer.setDateOfBirth(dob);
    
    		client.loadEntity(customer);
    }
    
    	private void sendEvents() throws Exception {
    		CustomerEvent ev =  client.getEventFactory()
    					.createEvent(CustomerEvent.class);
    		ev.setCustomerId("111");
    		client.submitEvent(ev);
    }
    }

    After running this test you should see the following message in the log:

    [21/11/14 15:04:57:962 GMT] 00000246 SystemOut O Mickey Mouse's age is 86

Conclusion

This tutorial described the process of creating an OSGi service and making it accessible from a rule by describing the service in a BOM. You learned how to use the service in a business rule and how to package the service in a Decision Server Insights solution. Using this process, you can extend capabilities available in the rules language and make it easier for rule writers to access and use more complex services.

Acknowledgements

The authors would like to thank Daniel Selman and Matt Roberts for their review of this tutorial.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Middleware
ArticleID=998694
ArticleTitle=Simplify complex code with OSGi services in Decision Server Insights rules
publish-date=03252015