Explore IBM Integrated Information Core model aware adapters

Extend adapters to support various data sources

Integrated Information Core is an IBM Industry Solutions product offering designed to help customers improve their operations. A semantic model provides access to operational data in context. This article describes the architecture of the data access through the semantic model. Learn about the data adapters provided with the product and how you can extend them to support customer-specific data sources. Through examples, explore how the model-aware adapters are constructed. Create new adapters to integrate sources of measurement data into a system so it can be referenced from the semantic model.

Share:

Tim Hanis (hanistt@us.ibm.com), Chief Architect, IBM Integrated Information Core, IBM

Author photoTim Hanis is the chief architect for the IBM Integrated Information Core product. He works in software product development in the Industry Solutions organization in Research Triangle Park, NC. He has led a number of development projects both within IBM software groups and with customer solution development and deployment. He has extensive experience helping customers solve business problems with IBM products.


developerWorks Contributing author
        level

Venkatesh Patil (venpatil@in.ibm.com), IT Architect, IBM

Photograph of Venkatesh PatilVenkatesh Patil (Venky) is a solution architect on the Industry Solutions team at the IBM India Software Lab. Venky is a certified IT Architect with 11 years of IT experience. He is skilled on various IBM products, including WebSphere Process Server, Websphere Portal, and Websphere Business Events. For four years his focus has been on developing model based frameworks for the automotive manufacturing, chemical, and petroleum industries. He has been a speaker at several conferences, including the Regional Technical Leadership Exchange, Software Universe, and manufacturing events.



Devi Panneerselvam (devi.panneer@in.ibm.com), IT Specialist, IBM

Photograph of Devi PanneerselvamDevi Panneerselvam, a Solution Developer on the Industry Solutions team at the IBM India Software Lab, has over five years of IT experience. Devi works on the IBM Integrated Information Core product. For the past three years she has focused on developing the database and web services model aware adapter framework. She has authored several articles and a redbook.



Ashish A. Kulkarni (ashiskul@in.ibm.com), IT Specialist, IBM

Photograph of Ashish KulkarniAshish Kulkarni is a solution architect on the Industry Solutions team at the IBM India Software Lab. Ashish has seven years of IT experience and skills on various IBM products, including Websphere MQ, Websphere Application Server, Process Server, and Websphere Business Events. For three years he has focused on developing model based frameworks for the automotive manufacturing, chemical, and petroleum industries. He has been a speaker at several conferences including, the Regional Technical Leadership Exchange, Software Universe, and manufacturing events.



07 February 2012

Introduction

Integrated Information Core is a software platform based on industry and IT standards. It is designed to help customers in process industries improve integrated operations in areas such as petroleum, manufacturing, asset condition monitoring, and mining exploration. A semantic model provides a critical integration point for information about instrumented equipment in a customer enterprise. The model describes:

  • The equipment (or asset).
  • The relationships between equipment.
  • References to measurement data that's provided by the equipment.

With the model, customers can understand how assets are deployed in their enterprise and build solutions accordingly. They can easily navigate through the model to find equipment of a certain type, with a set of specific relationships, or with a specific set of attributes. Queries yield responses through a contextual understanding of the overall deployment. The model also provides a canonical structure for normalizing the definition of similar assets--independent of manufacturer or model differences. With the canonical form, the application does not need to account for differences in asset definitions.

The model provides a reference to data that's obtainable from instrumented equipment, or from data stores or services that map to a similar structure for measurement data. Integrated Information Core has its origins with industrial automation and process control systems, and thus has integration points for OLE for Process Control (OPC) data. OPC, an industry standard from the OPC Foundation (see Resources):

  • Defines a set of programming interfaces to enable exchange of application data.
  • Is the predominant data exchange interface in the industrial automation industry.
  • Provides several interfaces, but by far the most frequently supported is the Data Access (DA) specification.

The DA specification supports a client/server interface for reading and writing "real-time" data. The second-most frequently adopted specification is the Historical Data Access interface (HDA), which provides a client/server interface for accessing time series data.

Frequently used abbreviations

  • DA: Data Access
  • GID: Generic Interface Definition
  • HDA: Historical Data Access
  • HSDA: High Speed Data Access
  • OPC: OLE for Process Control
  • RSM: Reference Semantic Model
  • TSDA: Time Series Data Access
  • WSDL: Web Services Description Language
  • XML: eXtensible Markup Language

The specification for data exchange defines a simple data structure. An OPC data element, whether real time or time series based, contains:

  • An ID
  • A time stamp
  • A quality indicator
  • A simple data element representing the data value

This structure is more generically called measurement data.

Since Integrated Information Core has a heritage in the industrial process industry, the product has references in the semantic model to: measurement data, a data access infrastructure that supports measurement data, and a set of data source adapters that provide access to measurement data.

Today, Integrated Information Core provides data adapter capability to support the query and retrieval of measurement data from OPC servers, database tables, or web services. It provides an extensible infrastructure so other data sources can also be referenced.

As mentioned, the adapters need to be model aware. Integrated Information Core includes integration points, between the model server and the references to data elements described in the model, in a globally defined namespace. When any specific data element is referenced, you need to be able to map from the model structure to the appropriate data adapter and then ultimately to the correct data element that is managed through that adapter. In this way, adapters are model aware--they can retrieve the correct data, even as the data is referenced through model organization and naming.

In this article, learn in detail how model aware adapters are constructed. An example shows how to create new adapters to integrate other sources of measurement type data into the system so it can be referenced from the semantic model. See how to provide customer value by finding asset definitions, and the sources of real time data associated with those assets--even if the sources are in a different form than the adapters provided with the product.

Download the source code used in this article.


The Reference Semantic Model

The Reference Semantic Model (RSM) is an implementable model that manufacturing companies (process industries, oil and gas, automotive, aerospace, and so on) can use to connect measurements, planning and scheduling, and life cycle management throughout the enterprise. RSM is not a data model; it does not constrain the way applications implement the information contained within the model. This model is designed to facilitate the exchange of information.

RSM is governed by the standards from which it is made. The original intention was to create a model that harmonized the ISA-88 and ISA-95 standards. But, the following parts of the enterprise business model weren't covered by these two standards: design life cycle, physical connectivity of equipment, and process versus electrical distribution. These gaps were filled with standards chosen from working experience or based on current harmonization work with the ISA standards. The standards were then logically linked together at appropriate places to form an enterprise-wide information model. The standards that comprise the RSM are:

  • ISA-88/BatchML
  • ISA-95/B2MML
  • ISO 15926
  • IEC 61968/IEC 61970
  • ISO 13374 (MIMOSA)
  • UN/CEFACT Core Components
  • SI Derived Units
  • OPC
  • OAGIS

Adapters architecture

IBM Model Aware Adapters have two major components: the adapter and a connector. Figure 1 shows the IBM Model Aware Server Adapter architecture.

A connector is a web service implementation of a standard interface defined specifically for real time and time series data access. The underlying implementation of the interface is specific to the customer data source. As an extension to the product, Integrated Information Core provides tools to generate the connector for RDBMSs.

An adapter is standard implementation of Generic Interface Definition (GID) interfaces. It acts as the front end to the client adapters and contains the mappings of model elements with the exact points of interest in the connector datasource with which it's configured. Figure 1 shows the IBM Model Aware Server Adapter architecture.

Figure 1. IBM Model Aware Server Adapter architecture
library

Connector

Connectors are implementations of standard DA and HDA interfaces provided by the Model Aware Adapter architecture of Integrated Information Core. The connectors are basically web services that can be created using many tools, such as IBM WebSphere Integration Developer or IBM Rational Application Developer. Connectors interact with adapters and a data source. The data source could be a database, a flat file, or any other type of data source. For a database, a database connector is created. For any other type of data source, a web service is created that in turns talks to the data source.

See the IBM Integrated Information Core Information Center (Resources) for more about the API.

A connector gets inputs from an adapter and interacts with the data source to retrieve information and send it back to the adapter. Although we are calling them DA/HDA or HSDA/TSDA, the connector interfaces are only similar to them and are not really the standard interfaces. Connectors can be of two types: Time Series Data Access (TSDA) or High Speed Data Access (HSDA). Each connector has to be exposed in its interface specification.

Webservice connector

Webservice connector is middleware between an adapter and a web service, which reads and writes data from the data source. The web service that reads and writes data needs to be exposed in specified interface format based on the type of adapter: HSDA (near real time data) or TSDA (time series data).

In the following sections you will:


Create a web service

You'll start by using the sample web service CustomerWebServiceEAR.zip (Downloads), which needs to be deployed on the server, along with the mediation project (explained in Expose a web service in the specific interface format). If you already have your own web service, you can skip this step and expose the web service to the specific interface (see Expose a web service).

  1. Open a work space in WebSphere Integration Developer.
  2. From Downloads, import the CustomerWebservicePI.zip. The project interchange contains three projects:
    • CustomerWebService Webservice Project
    • CustomerWebServiceEAR - Enterprise Application Project
    • WSConnectorLib - Library project with interface details for the web service
  3. In the CustomerWebservice Project is a single Java class with three methods and a hashmap variable that is initially loaded with two tags: tag1 and tag2. They have measurement values of 10.2 and 6.8, respectively. See Listing 1.

    Listing 1. Tag List
    static{
    		tagValuesMap.put("tag1", 10.2);
    		tagValuesMap.put("tag2", 6.8);
    	}

    The LoadTags method returns a string array of tag values. It returns all the keys in the hashmap variable, as in Listing 2.

    Listing 2. LoadTags
    public String[] LoadTags(){
    		String[] tagList=new String[tagValuesMap.size()];
    		Iterator<String>iter=tagValuesMap.keySet().iterator();
    		int count=0;
    		while(iter.hasNext()){
    			tagList[count++]=(iter.next());
    		}
    		return tagList;

    The readMeasurementValue method takes a tag as input and returns a ValueObject, which includes the measurement value for this tag from the hashmap variable and current timestamp. See Listing 3.

    Listing 3. ReadMeasurementValue
    public ValueObject readMeasurementValue(String tag){
    		ValueObject val=new ValueObject();
    		val.setTag(tag);
    		SimpleDateFormat currentdateFormat = new SimpleDateFormat
    		("yyyy-MM-dd HH:mm:ss");
    		currentdateFormat.setTimeZone(TimeZone.getTimeZone("IST"));
    		String timestamp=currentdateFormat.format( new Date() );
    		
    		val.setTimestamp(timestamp);
    		if(tagValuesMap.containsKey(tag)){
    		val.setMeasurementvalue(String.valueOf(tagValuesMap.get(tag)));
    		}
    			
    		return val;
    	}

    As shown in Listing 4, the writeMeasurementValue method takes tag and measurement value as input. This method updates the hashmap with the given tag and measurement value and returns true if its successful or false in case of failure.

    Listing 4. WriteMeasurementValue
    public boolean writeMeasurementValue(String tag,String measurementValue){
    		try{
    		System.out.println("Writing Measurement Value "+tag+" " 
    		+measurementValue);
    		if(tagValuesMap!=null && tag!=null ){
    			tagValuesMap.put(tag,Double.parseDouble(measurementValue));
    		}
    		System.out.println("Write Done");
    		}
    		catch(Exception e){
    			System.out.println("Exception in WriteMeasurementValue");
    			e.printStackTrace();
    			return false;
    		}
    		return true;
    	}

Expose a web service in the HSDA specific interface format

The next task is to expose the web service (imported in the previous section) under HSDA specific WSDL. Use the project interchange HSDAWSMediation.zip from Downloads.

  1. Import the IndFrwksMAAdapterLib.zip from Downloads into the workspace, as in Figure 2. This project interchange contains the HSDA and TSDA specific interface.
    Figure 2. Import the projects
    importProjects
  2. Create a mediation module and give it a name, as in Figure 3.
    Figure 3. Create mediation module
    MediationModule
  3. You need to add both library projects into the mediation because you're going to use the interface available in both projects. Open Dependencies in HSDAWSMediation, as in Figure 4.
    Figure 4. Add dependencies
    dependencies
  4. Click on Add under Libraries Selection and add both the Projects. Save by clicking OK, as in Figure 5.
    Figure 5. Add library
    library
  5. Expand the IndFrwksMAAdapterLib Project, and drag and drop the IIFMAHSDAAdapter interface into the assembly diagram of HSDAWSMediation.
  6. In the Component Creation window, select Export With Web Service Binding, as in Figure 6.
    Figure 6. Export with Web Service Binding
    exportWS
  7. Select SOAP1.1/Http using JAX-RPC for the Transport Protocol, as in Figure 7, and click Finish.
    Figure 7. Select transport protocol
    SOAP
  8. Expand the WSConnectorLib Project, as in Figure 8, and drag and drop the CustomerService interface into the assembly diagram of HSDAWSMediation.
    Figure 8. Add interface
    addInterface
  9. In the Component Creation window, select Import With Web Service Binding, as in Figure 9, and click OK.
    Figure 9. Import with Web Service Binding
    importWS
  10. As shown in Figure 10, click Browse and select CustomerService. Click OK.
    Figure 10. Select web service port
    WSPort
  11. Select Soap1.1/HTTP using JAX-RPC for the Transport Protocol. Click Finish.
  12. Wire the components in the assembly diagram, as in Figure 11. Click OK in the Add wire window.
    Figure 11. Assembly diagram
    AD
  13. In the assembly diagram, right click on the HSDAWSMediation component and select Generate Implementation.
  14. Select the HSDAWSMediation folder in the Generate Implementation window and click OK.
  15. Click on getListOfItemIds and select Operation Map.
  16. Select the method that needs to be called for getListOfItemIds. In this case, select the LoadTags method and click OK, as in Figure 12.
    Figure 12. Select reference operation
    RefOpe1
  17. Double click on input_map. Provide a name for the XML map, as in Figure 13, and click Finish.
    Figure 13. XML mapping
    xmlMap
  18. Map getListOfItemsIds to LoadTags, as in Figure 14.
    Figure 14. LoadTags request mapping
    loadReq
  19. Click the Response Tab of HSDAWSMediation and double click on output_map. Provide a name, as in Figure 15, and click Finish.
    Figure 15. XML mapping
    loadResMap
  20. Map String to ItemIds, as in Figure 16.
    Figure 16. Load response mapping
    loasRes
  21. Move to the Overview tab of HSDAWSMediation. Click Read and select Operation Map.
  22. Select the method that needs to called for Read. In this case, select the readMeasurementValue method, as in Figure 17, and click OK.
    Figure 17. Select reference operation
    RefOpe2
  23. Double click on input_map. Provide a name for the XML map, as in Figure 18, and click Finish.
    Figure 18. Read input mapping
    readInputMap
  24. Map ItemId to tag, as in Figure 19.
    Figure 19. Read input mapping, cont.
    readInputMapping
  25. Click the Response tab of HSDAWSMediation and delete output_map. From the left palette, drag and drop Custom Mediation from under the Transformation folder. Do the mapping, as in Figure 20.
    Figure 20. Read response mapping
    readResponseCM1
  26. As shown in Figure 21, select CustomMediation1 and click Details in the Properties view.
    Figure 21. Read response mapping, cont.
    readResponseCM
  27. Copy the code snippet in Listing 5 and paste it in the Details. This code snippet gets the response from webservice and packages it in a HSDAReadOut form.
    Listing 5. Read response custom mediation code
    ServiceManager serviceManager = new ServiceManager();
    BOFactory boFactory = (BOFactory)serviceManager.
    locateService("com/ibm/websphere/bo/BOFactory");
    QName qName = new QName("http://MAAdapterLib/IIFMAHSDAAdapter","readResponseMsg");
    ServiceMessageObjectFactory smoFactory = ServiceMessageObjectFactory.eINSTANCE;
    ServiceMessageObject responseSMO = smoFactory.createServiceMessageObject(qName);
    
    DataObject readResponse= boFactory.
    createByElement("http://MAAdapterLib/IIFMAHSDAAdapter","readResponse");
    DataObject readOutObj = readResponse.createDataObject("readOut");
    
    try{
    DataObject inputObj=(DataObject)smo.getDataObject("body").
    getDataObject(0).getDataObject("readMeasurementValueReturn");
    //Parsing Input Object
    String itemId=inputObj.getString("tag");
    String measurementValue=inputObj.getString("measurementvalue");
    String timestamp=inputObj.getString("timestamp");
    
    //Create SimpleType Value Object
    
    DataObject simpleTypeValueObj=
    (DataObject)boFactory.create("http://MAAdapterLib","SimpleTypeValue");
    simpleTypeValueObj.set("value",measurementValue);
    //Create ResponseObject
    
    
    DataObject readItemValueObj=
    (DataObject)boFactory.create("http://MAAdapterLib","ReadItemValues");
    readOutObj.set("value",simpleTypeValueObj);
    readOutObj.setString("timestamp",timestamp);
    readOutObj.setString("quality","GOOD");
    readOutObj.setString("itemId",itemId);
    readOutObj.setString("datatype","undefined");
    readOutObj.setString("uom","undefined");
    }
    catch(Exception e){
    System.out.println("Exception while retriveing data");
    e.printStackTrace();
    }
    ((DataObject)responseSMO.getBody()).set(0,readResponse);
    out.fire(responseSMO);
  28. Click on Java Imports in the Properties view and copy the import statements in Listing 6.
    Listing 6. Read response custom mediation code
    import commonj.sdo.DataObject;
    import com.ibm.websphere.sca.ServiceManager;
    import com.ibm.websphere.bo.BOFactory;
    import javax.xml.namespace.QName;
    import com.ibm.websphere.sibx.smobo.ServiceMessageObjectFactory;
    import com.ibm.websphere.sibx.smobo.ServiceMessageObject;
  29. Move to the Overview tab of HSDAWSMediation. Click Write, and select Operation Map.
  30. Select the method that needs to be called for write. In this case, select the writeMeasurementValue method and click OK.
    Figure 22. Select reference operation
    writeOM
  31. Delete the input_map. From the left palette, drag and drop Custom mediation under the Transformation Category. Do the mapping, as in Figure 23.
    Figure 23. Write input mapping
    writeInputMap
  32. Select CustomMediation1 and click Details in the Properties view. Copy the code in Listing 7 and paste it in the Details. The code snippet gets the request and packages it in a writeMeasurementValue form.
    Listing 7. Write input custom mediation code
    try{ 
    DataObject requestObject = (DataObject)smo;
    DataObject writeHSDAIn=((DataObject)smo).getDataObject("body").
    getDataObject("write").getDataObject("writeIn");
    String itemId = writeHSDAIn.getString("itemId");
    String quality = writeHSDAIn.getString("quality");
    String value = writeHSDAIn.getDataObject("value").getString("value");
    System.out.println("Updating " +itemId+" with value: "+value);
    //Prepare output
    ServiceManager serviceManager = new ServiceManager();
    BOFactory boFactory = 
    (BOFactory)serviceManager.locateService("com/ibm/websphere/bo/BOFactory");
    QName qName = new QName("http://DefaultNamespace","writeMeasurementValueRequest");
    ServiceMessageObjectFactory smoFactory = ServiceMessageObjectFactory.eINSTANCE;
    ServiceMessageObject responseSMO = smoFactory.createServiceMessageObject(qName);
    DataObject csInputObj= 
    boFactory.createByElement("http://DefaultNamespace","writeMeasurementValue");
    
    if(csInputObj!=null){
    csInputObj.setString("tag",itemId);
    csInputObj.setString("measurementValue",value);
    }
    else{
    System.out.println("csInputObj is null");
    }
    ((DataObject)responseSMO.getBody()).set(0,csInputObj);
    out.fire(responseSMO);
    }
    catch(Exception e){
    System.out.println("Exception Happened in Write");
    e.printStackTrace();
    }
  33. Select Java Imports in the Properties view and copy the import statements in Listing 8.
    Listing 8. Write input custom mediation code, cont.
    import commonj.sdo.DataObject;
    import com.ibm.websphere.sca.ServiceManager;
    import com.ibm.websphere.bo.BOFactory;
    import com.ibm.websphere.sibx.smobo.ServiceMessageObjectFactory;
    import com.ibm.websphere.sibx.smobo.ServiceMessageObject;
    import javax.xml.namespace.QName;
  34. Click the Response Tab of HSDAWSMediation and double click on input_map. As shown in Figure 24, provide a name for the XML map and click Finish.
    Figure 24. Write output mapping
    writeOutMap
  35. Do the mapping, as shown in Figure 25.
    Figure 25. Write output mapping cont.
    writeOutMapping

    (View a larger version of Figure 25.)

  36. Save your work. Export HSDAWSMediation as an EAR file and deploy it to the server.

Expose a web service in the TSDA specific interface format

To expose a web service in TSDA specific WSDL, you follow almost the same steps as in the previous section. Use the TSDAWSMediation.zip file in Downloads. For the TSDA specific WSDL, you need to import the IIFMATSDAAdapter interface in Step 5 (in previous section) and do the mapping accordingly.

Continue following the steps in the previous section until Step 20. After that step, begin using the steps below.

  1. Click on the readHistorical method and select Blank Mediation Flow.
  2. From the left palatte, drag and drop custom mediation from the Transformation category.
  3. Select CustomMediation1 and click Details in the Properties view.
  4. Copy the code snippet in Listing 9 and paste it in the Details. This code snippet calls the web service for every item ID and populates it into the response object.
    Listing 9. ReadHistorical custom mediation code
    DataObject requestObject = (DataObject)smo;
    DataObject readTSDAIn=((DataObject)smo).getDataObject("body").
    getDataObject("readHistorical").getDataObject("readTSDAIn");
    String startDate = readTSDAIn.getString("startDate");
    String endDate = readTSDAIn.getString("endDate");
    boolean bounds = readTSDAIn.getBoolean("bounds");
    List itemIds = readTSDAIn.getDataObject("itemIds").getList("ItemIds");
    
    
    //Prepare output
    ServiceManager serviceManager = new ServiceManager();
    BOFactory boFactory = (BOFactory)serviceManager.
    locateService("com/ibm/websphere/bo/BOFactory");
    //DataObject readOutObj=(DataObject)boFactory.
    create("http://MAAdapterLib","ReadTSDAOut");
    QName qName = new 
    QName("http://MAAdapterLib/IIFMATSDAAdapter","readHistoricalResponseMsg");
    ServiceMessageObjectFactory smoFactory = ServiceMessageObjectFactory.eINSTANCE;
    ServiceMessageObject responseSMO = smoFactory.createServiceMessageObject(qName);
    
    DataObject readHistoricalResponse = boFactory.
    createByElement("http://MAAdapterLib/IIFMATSDAAdapter","readHistoricalResponse");
    DataObject readOutObj = readHistoricalResponse.createDataObject("readTSDAOut");
    
    
    Vector readOutItems=new Vector();
    DataObject readOutItemObj=null;
     	for(int i=0;i<itemIds.size();i++){
    		String operationName="readMeasurementValue";
    		BOFactory boFactory1 = (BOFactory)serviceManager
    .locateService("com/ibm/websphere/bo/BOFactory");
    		QName qName1 = new 
    QName("http://DefaultNamespace","readMeasurementValueRequest");
    		ServiceMessageObject requestSMO = smoFactory.
    createServiceMessageObject(qName);
    		DataObject csInputObj= boFactory1.
    createByElement("http://DefaultNamespace","readMeasurementValue");
    		if(csInputObj!=null){
    			csInputObj.setString("tag",(String) itemIds.get(i));
    		}
    		else{
    			System.out.println("csInputObj is null");
    		}
    		Vector readItemValues = new Vector();
    		//Call Webservice
    		Service csService=(Service) ServiceManager.
    INSTANCE.locateService("CustomerServicePartner");
    		DataObject csResponse=(DataObject)csService.
    invoke(operationName,csInputObj);
    		//Parse response msg
    		DataObject inputObj=(DataObject)csResponse.getDataObject(0);
    		String itemId=inputObj.getString("tag");
    		String measurementValue=inputObj.getString("measurementvalue");
    		String timestamp=inputObj.getString("timestamp");
    
    		//Create SimpleType Value Object
    		DataObject simpleTypeValueObj=(DataObject)boFactory.
    create("http://MAAdapterLib","SimpleTypeValue");
    		simpleTypeValueObj.set("value",measurementValue);
    		//Create ResponseObject
    		DataObject readItemValueObj=(DataObject)boFactory.
    create("http://MAAdapterLib","ReadItemValues");
    		readItemValueObj.set("value",simpleTypeValueObj);
    		readItemValueObj.setString("timestamp",startDate);
    		readItemValues.add(readItemValueObj);
    		readOutItemObj=(DataObject)boFactory.
    create("http://MAAdapterLib","ReadOutItem");
    		readOutItemObj.set("itemId",itemIds.get(i));
    		readOutItemObj.setString("dataType","String");
    		readOutItemObj.setString("uom","");
    		readOutItemObj.setList("readItemValues",readItemValues);
    		readOutItems.add(readOutItemObj);
    		
    	}
    //Add it to output
    readOutObj.setList("itemList",readOutItems);
    ((DataObject)responseSMO.getBody()).set(0,readHistoricalResponse);
    out.fire(responseSMO);
  5. Select Java Imports in the Properties view and copy the import statements in Listing 10.
    Listing 10. ReadHistorical custom mediation code, cont.
    import commonj.sdo.DataObject;
    import com.ibm.websphere.sca.ServiceManager;
    import com.ibm.websphere.bo.BOFactory;
    import javax.xml.namespace.QName;
    import com.ibm.websphere.sibx.smobo.ServiceMessageObjectFactory;
    import com.ibm.websphere.sibx.smobo.ServiceMessageObject;
    import java.util.Vector;
    import com.ibm.websphere.sca.Service;
    import java.util.List;
  6. Move to the Overview tab of TSDAWSMediation. Click writeHistorical and select Operation Map.
  7. Select the method that needs to be called for write. In this case, select the writeMeasurementValue method. Click OK.
  8. Delete the input_map. From the left palette, drag and drop Custom mediation under the Transformation category. Do the mapping (similar to step 31 of the HSDA specific WSDL).
  9. Select CustomMediation1 and click Details in the Properties view. Copy the code snippet in Listing 11 and paste it in the Details. This code snippet gets the request and packages it in writeMeasurementValue form.
    Listing 11. Write input custom mediation code
    try{ 
    DataObject requestObject = (DataObject)smo;
    DataObject writeTSDAIn=((DataObject)smo).getDataObject("body").
    getDataObject("writeHistorical").getDataObject("writeIn");
    String itemId = writeTSDAIn.getString("itemIds");
    String quality = writeTSDAIn.getString("quality");
    String value = writeTSDAIn.getDataObject("value").getString("value");
    System.out.println("Updating " +itemId+" with value: "+value);
    //Prepare output
    ServiceManager serviceManager = new ServiceManager();
    BOFactory boFactory = (BOFactory)serviceManager.
    locateService("com/ibm/websphere/bo/BOFactory");
    QName qName = new QName("http://DefaultNamespace","writeMeasurementValueRequest");
    ServiceMessageObjectFactory smoFactory = ServiceMessageObjectFactory.eINSTANCE;
    ServiceMessageObject responseSMO = smoFactory.createServiceMessageObject(qName);
    DataObject csInputObj= boFactory.
    createByElement("http://DefaultNamespace","writeMeasurementValue");
    
    if(csInputObj!=null){
    csInputObj.setString("tag",itemId);
    csInputObj.setString("measurementValue",value);
    }
    else{
    System.out.println("csInputObj is null");
    }
    ((DataObject)responseSMO.getBody()).set(0,csInputObj);
    out.fire(responseSMO);
    }
    catch(Exception e){
    System.out.println("Exception Happened in Write");
    e.printStackTrace();
    }
  10. Select Java Imports in the Properties view and copy the import statements in Listing 12.
    Listing 12. ReadHistorical Custom Mediation Code, cont.
    import commonj.sdo.DataObject;
    import com.ibm.websphere.sca.ServiceManager;
    import com.ibm.websphere.bo.BOFactory;
    import com.ibm.websphere.sibx.smobo.ServiceMessageObjectFactory;
    import com.ibm.websphere.sibx.smobo.ServiceMessageObject;
    import javax.xml.namespace.QName;
  11. Click on the Response Tab of TSDAWSMediation and double click on input_map. Provide a name for the XML map and click Finish. Do the mapping, similar to step 35 in HSDA specific WSDL.
  12. Save your work. Export the TSDAWSMediation as an EAR file and deploy it to the server.

Create a Webservice connector using Solution Studio

A Webservice connector has to be created using the end point URL of the web service created in the previous section. For information about creating a Webservice connector using Solution Studio, in the Integrated Information Core Information Center see: IBM Integrated Information Core -> Creating IBM Model Aware Adapters -> Creating the Webservice Adapter using Solution Studio.

Database connector

A database connector reads and writes measurement values from and to a database. In IBM Integrated Information Core Version 1.4, a database connector supports only a single table. The queries to retrieve the list of tags, and the query to read/write a measurement value, cannot have a join query. If the customer database has multiple tables, a view has to be created from these tables and a database connector has to be created for the view. Integrated Information Core V1.4 allows the user to create a database connector for three database types: DB2, Oracle, and MS-SQL.

While creating a connector, Solution Studio displays sample queries that have to be replaced with the query for the customer database. In the where clause, the terms enclosed with $$ are the variables that get replaced by runtime values. For example, $$STARTDATE$$ gets replaced with the start date passed by the adapter. Hence, for the user to use runtime values they need to use the appropriate terms: ITEMID, TAG, STARTDATE, ENDATE enclosed by $$.

For information about creating a database connector using Solution Studio, in the Integrated Information Core Information Center see: IBM Integrated Information Core -> Using IBM Integrated Information Core components -> Using Solution Studio -> Managing adapters -> Creating and configuring a new adapter -> Creating a connector.


Server Adapter

The Server Adapter component of the IBM Model Aware Adapter module is its primary interface to the client adapter. The Server Adapter also acts as a front end to the data server, thereby enabling the data interchange between the data server and the applications through the client adapter. It implements two standard interfaces: the GID's HSDA and TSDA. It acts as an HSDA and TSDA server to the various client applications wanting to interchange data with the data server. In this section, learn more about these interfaces and the Server Adapter design.

Generic Interface Definition (GID)

GID is an interface standard modeled on the widely used OPC interface standard developed by the OPC Foundation (see Resources). OPC is dominant in industrial automation and process control industries. It provides connectivity to many key applications. All the major application providers support OPC. Two of its interfaces that provide standardized data interchange are:

  • OPC DA - client/server interface for reading, writing, and reporting real-time data.
  • OPC HDA - client/server interface for accessing data archives.

OPC is based on Microsoft COM technology and therefore needed a standardized and technology-neutral method of representing data. Enter GID, which provides standardized interface services. GID is part of the IEC 61970. The interfaces reference data in the context of a common data exchange model which, for Integrated Information Core, is the Common Information Model (CIM) based RSM. The following GID services closely follow the OPC DA and HDA interfaces:

  • HSDA for access to real-time measurement data, described in Part 404 of IEC 61970 (see Resources).
  • TSDA for access to historical measurement data, described in Part 407 of IEC 61970 (see Resources).

You are encouraged to read about the interface standards, and Part 4 of IEC 61970, for a more detailed understanding.

The rest of this section outlines the Server Adapter's implementation for realizing these interfaces. The sections are divided loosely on the major themes of the interfaces.

Browse

Server Adapter is a server-like implementation that takes care of client subscription management, concurrency, state management, synchronization of client and server requests-responses, and performance. It:

  • Is written completely in Java and implemented as an Enterprise JavaBean.
  • Runs in a Websphere Application Server environment and exploits several of its features.
  • Primarily uses its messaging infrastructure to exchange messages with the client adapter.

    The messages themselves use XML as the data interchange format and carry HSDA or TSDA requests and responses as payload.

The Browse function enables the client adapter to browse the server's address space. As described in the Adapter configuration, each Server Adapter instance addresses a subset of the entire enterprise model, which is loaded and mapped to the entities as part of the adapter configuration. It is this mapped model that the client adapter requests in a sequence of HSDA browse requests. The HSDA Browse API itself defines more than one operation and specifies different request payload based on whether it is a class, instance, or item browse.

The Server Adapter integrates with the Model Mapping Services subcomponent to respond to the browse requests. The Model Mapping Services persists the classes, instances, and their properties, mapping information in a back-end database. All the information is cached using the WebSphere Application Server's DynaCache mechanism, which reduces the response times to the series of browse requests received by the Server Adapter. The client adapter browses the model one node at a time, in a depth-first fashion, starting from the root enterprise node down to the item. The caching significantly affects the database access, thereby improving the performance.

The Server Adapter performs further optimizations, such as pre-fetching all the instance and property details for the mapped instances. It walks the model hierarchy bottom-up, starting from the mapped items, all the way up to the root node, and bread-crumbs the instances encountered. As part of the marking process, the Server Adapter also enriches each node with a list of its children. This is extremely helpful when responding to the instance browse requests where the client adapter requests the child nodes of a node. The Server Adapter also handles scenarios where a node might have multiple parents and therefore multiple paths in the model. The Server Adapter "remembers" the path being browsed by the client adapter and resolves the correct path to address such cases.

Subscriptions

The client registers interest in measurement values by subscribing to measurement items from the model. The client then receives periodic updates to the values for those measurements. The HSDA interface specification allows the client to specify the list of subscribing items, the refresh period, and other parameters. The default group subscription refresh rate is set at 1000ms at the client. The Server Adapter itself maintains a maximum allowed refresh rate at the connector level. This is the rate at which it can poll the back-end data source. Any rate faster than that coming from the client is overridden while a rate slower than that is honored. This control mechanism puts a check on the back-end traffic and keeps it within what might be acceptable to the data source.

The Server Adapter:

  • Updates the subscriptions using the WebSphere Alarm feature.
  • Maintains two objects per adapter instance via a subscription cache containing all the subscribed items and a WebSphere Alarm.

    Each adapter instance can have multiple subscriptions.

The cache holds the subscribed items ordered by their subscription handle, which uniquely identifies a subscription. Each subscription has its own refresh rate that might get overridden (as explained above).

The alarm is created with a snooze rate that's the same as the adapter (or connector) level refresh rate. The alarms goes off at the snooze rate. The server adapter subscription refresher then sweeps the subscription cache. For each subscription, it checks if it has passed its sampling time and then updates the values for the items in that subscription. Sampling time is determined based on the refresh rate of that subscription. After each successful refresh, it updates the next sampling time for that subscription. As you would imagine, the subscription refresh might not happen exactly at the sampling time. For example, there are three subscriptions with refresh rates of 4 minutes, 7 minutes, and 8 minutes and the adapter level refresh rate (same as alarm snooze rate) is set at 3 minutes. The first subscription will get updated after 6 minutes, all of them will be updated again after 9 minutes, and so on.

The Server Adapter interacts with the Connector service for data retrieval operations. The Connector acts as a front end to the data source. In addition to other operations, it exposes two operations for real-time and historical data retrieval. The Server Adapter calls these two operations in response to data requests from the OPC clients. The connector also gets called when the adapter refreshes the subscription values.

HSDA read and write

The client can also issue synchronous read and write requests to the Server Adapter. The Server Adapter responds to these requests by calling the corresponding connector instance. Any timestamps sent to or from the client are in the UTC time zone. The Server Adapter converts the time to a time zone and format as specified in the connector configuration.

TSDA read and write

The client can issue a historical read or write request to the adapter. The request can contain a group of item IDs. The read request may be for either raw data or for processed data. The TSDA standard interface specifies a list of aggregate functions. The Server Adapter calls the connector for raw data or writing historical data. The Server Adapter applies the aggregate functions on the raw data while responding to requests for processed data. Again, any timestamps passed to the connector are converted to a time zone and format configured in the connector.

Configuration

See the Integrated Information Core Information Center (Resources) for configuration information.


Conclusion

In this article, you learned how Integrated Information Core provides a framework that lets customers improve their operations through enhanced data access and understanding. With Integrated Information Core's near real-time, integrated information, customers can increase production and reduce costs by extending their use of data coming from enterprise production units. Integrated Information Core provides a semantic model that represents interconnected and instrumented equipment in enterprise-level production processes. The model, which defines the equipment and relationships, is also used to represent the measurement data that's available from that equipment or other data sources.

To retrieve real-time and historical data from various data sources, Integrated Information Core defines a data server adapter component structure. Integrated Information Core includes several data adapters, such as an adapter to support integration to industry standard device and server sources. Other adapters support integration to technology interfaces, such as web services and database access. The adapters need to be model aware in order to support the references to data as it is reflected in the semantic model. This article discussed the architecture of model aware adapters and the component structure of the adapters. You learned how to extend the adapters to support specific data sources through the web service and database access interfaces.

A future article will provide detailed steps for creating a new adapter and deploying it into an Integrated Information Core environment to support the integration of a new data source through the semantic model.


Downloads

DescriptionNameSize
Sample Web Service EARCustomerWebServiceEAR.zip10KB
Project Interchange Sample Web Service ConnectorCustomerWebservicePI.zip21KB
HSDA Mediation PIHSDAWSMediation.zip43KB
HSDA/TSDA Interface definitionIndFrwksMAAdapterLib.zip17KB
TSDA Mediation PITSDAWSMediation.zip45KB

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=790985
ArticleTitle=Explore IBM Integrated Information Core model aware adapters
publish-date=02072012