Java/XML API Reference (IEC Library)

The SAP CC 2023 Java API Reference (IEC Library) documentation is intended for developers that need to implement business services provided by IEC (Import/Export Connector), a software component of the SAP Convergent Charging (SAP CC) software product. The necessary Java libraries are included in a dedicated Software Development Kit (Core SDK).

Caution

Make sure that you have the latest version of this documentation extracted from the Core SDK.

Target Audience

  • Development consultant
  • Technology consultant
  • Implementation project team

Overview

This SAP product document presents how to implement a Java class plugged to an SAP CC Import/Export Connector (IEC) application in your SAP system landscape to customize its business or technical behavior by adding the following features:

  • Functional processing features regarding to your business requirements (see the JavaTask abstract Java class)
  • Logging features (see the UserLogger Java interface)
  • Reporting features when working with the SAP CC BART Server system; see the com.highdeal.bart.iec.AcquisitionSessionReportHandler Java interface (SAP site)

    • Features

    These SAP CC Java libraries provide you with the necessary Java classes and Java interfaces to develop a Java class to customize the behavior of an SAP CC Import/Export Connector (IEC) application in your system landscape.

    Implementation in Your Customized IEC Application

    During the planning and preparation steps of your project implementation phase, you develop the relevant Java class that can be plugged in an IEC application:

    Depending on your business requirements, you design and develop your customized Java classes detailed in this section:

    Java Class for the Java Action Component

    When you need to add and set up a Java Action component in a scenario configured with the SAP CC CAT Tool user interface, you must develop a Java class that can be specified in this scenario and executed by an Import/Export Connector (IEC) application.

    To implement a Java Action in a scenario, you have to:

    To compile this task you need the iec.jar file in your Java compiler classpath.

    Once developed, you specify your Java class (Java Task) in the relevant customized scenario and component: Set up a Java Action component with CAT Tool.

    Java Class for the Log Action Component

    When you need to add and customize a Log Action component in a scenario configured with the SAP CC CAT Tool user interface, you must develop a Java class that can be specified in this scenario and executed by an Import/Export Connector (IEC) application.

    Your customized Java class must implement the UserLogger Java interface. To implement this interface, you must develop its five methods:

    • UserLogger.init()
    • UserLogger.close()
    • UserLogger.terminated(DataCollection, String)
    • UserLogger.rejected(DataCollection, String, String[], String)
    • and UserLogger.filtered(DataCollection, String, String[], String)

      To compile this Java class you need the iec.jar file in your Java compiler classpath.

      Once developed, you specify your Java class in the relevant customized scenario and component: Set up a Log Action component with CAT Tool.

      Java Class for the BART Acquisition Session Component

    • A Java class for the BART Acquisition Session Component to customize the behavior of the acquisition sessions between an IEC application and the BART Server system, allowing BART (*) to acquire consumption detail records (CDRs) converted from extended chargeable items (XCIs) and processed by the IEC application

      When you need to add a BART Acquisition Session component in a scenario configured with the SAP CC CAT Tool user interface, you must develop a Java class that can be specified in this scenario and executed by an Import/Export Connector (IEC) application.

      Design and develop a Java class that implements the com.highdeal.bart.iec.AcquisitionSessionReportHandler Java interface. By using a BART Acquisition Session component in a scenario, you can configure a Connector application to execute this Java class. A scenario is created with SAP CC CAT Tool.

      To compile this Java class you need the bart-iec.jar file in your Java compiler classpath.

      Once developed, you specify your Java class in the relevant customized scenario and component: Set up a BART Acquisition Session component with CAT Tool.

      Important Note

      This documentation does not provide any information about how to implement such a Java class. Refer to the SAP CC BART Java/XML API Reference.

      API Specification

      The application programming interface (API) specification defines the interaction between an SAP CC Import/Export Connector (IEC) application and a customized Java class plugged to this IEC application.

      This API specification has the form of a Java API also named Javadoc.

      Java APIs

      Configuration

      With the SAP CC Connector Administration Tool (CAT Tool) user interface, you create a scenario that specifies the behavior of the SAP CC Import/Export Connector application that will use this scenario as configuration file.

      When you add some specific scenario components you need to develop customized Java classes and to configure the scenario component with the details of the Java classe(s) you have developed with the SAP CC Java libraries.

      Once compiled, place your development in the classpath of the Import/Export Connector (IEC) applications in your system landscape: add your classes or jar in the <IEC_HOME>/jars/ folder.

      Note

      It is not recommended to modify directly the launch script of the connector application to add your directory to the classpath. Prefer the copy of your implementation to the <IEC_HOME>/jars/ folder.

      Implementation Tutorial

      Implementation Tutorial #1: Java Action

      This section describes how to implement a Java Action that can be specified in a scenario executed by an Import/Export Connector application in your system landscape.

      To illustrate this tutorial, let's take an original example, which will receive a name from the previous action and will send the string "HELLO "+name to the next action. It can be very funny if name is "WORLD", I let you imagine.

      Step 1

      To add a Java Action component in a scenario, you have to create first a Java class, com.mycompany.iec.Hello that extends the abstract class JavaTask. Implement the following two methods:

      Let's back to our example, we create a class: com.mycompany.iec.Hello

      package com.mycompany.iec; import java.util.Properties; import com.highdeal.iec.action.JavaTask; /** * This class generates the message "HELLO+[name]" and * makes it available to the next action. * The mandatory initialization properties are: * <ul> * <li>"nameIKey": the key that maps the property "name" in the DataCollection</li> * <li>"nameOKey": the key that will map the property "message" in the DataCollection</li> * </ul> */ public class Hello extends JavaTask { public void setProperties(Properties props) throws CannotInitializeException { // Get the key with which the name will be mapped nameIKey = props.getProperty("nameIKey"); // Get the key with which the message "HELLO+name" will be mapped and // available to the next action. msgOKey = props.getProperty("msgOKey"); } public DataCollection execute(DataCollection collection) throws ExecException { // Get the name // The name is extracted from the collection with the key //initialized in the method "getProperties". String name = collection.getString(nameIKey); // Generate the message String msg = "HELLO "+name; // Make the message available to the next action. // The message is mapped with the key initialized in the method // "getProperties". collection.setString(msgOKey, msg); return collection; } // The key with which the name is mapped private String nameIKey; // The key which will map the output message. private String msgOKey; }

      Note

      To compile this task, you need the iec.jar library file in you Java compiler classpath.

      Step 2

      Having do that, you have to declare your task in a scenario. Simply create a new scenario with the CAT Tool user interface and insert a Java Action Component. The next step describes how to configure this component.

      Note

      If you are interested by the final state of a DataCollection, your JavaTask has to implement the interface JavaTaskStateListener. This interface is the following:

      Step 3

      • Launch the CAT Tool user interface and create a new scenario.
      • Insert a Java Action component. This component allows you to execute any tasks adapted to your specific business needs.
      • Configure this component by defining the environment to execute a Java class:
        • In the Java Class Name text box, enter the Java class name to be executed by the Import/Export Connector (IEC) application: com.mycompany.iec.Hello

        • Fill in the first table (Module properties):
          Each line added to the table makes up a property used for initializing fields of the Java class. For each line added, type a property name (Key) and its Value.
          In our example because we need two initialization properties we should have two lines, one for the property nameIKey and the other for property msgOKey. The line nameIKey, message means that a previous action has put in the DataCollection a String mapped with the key "name" that contains the value to be used to generate the message.

        • Fill in the second table (Module context properties):
          Each line added to the table makes up an expected property returned by the Java class. For each line added, type a property Name and its Type (number, string, and so on). These properties will make up a new data collection usable by the next components in the tree.
          In our example, we have to declare that the task generates a String that will be mapped with the key "message" in the DataCollection. This makes the property "message" available to the next actions.

      Step 4: Execution of the Java Action

      Make sure that the Import/Export Connector application can access to Java classes referenced by the Java Action component in your scenario. Execute your new scenario in an IEC application:

      Implementation Tutorial #2: Log Action

      The following example shows you how to implement the UserLogger interface. This example shows the ConsoleLogger class that is used to print each event on a console:

      Example

      /* * * Copyright (C) 2013 SAP AG All Rights Reserved. * * NOTICE: The information contained in this document is subject to change * without notice. * * SAP AG MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS MATERIAL INCLUDING * BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR * A PARTICULAR PURPOSE. * * SAP AG shall not be liable for errors contained here in or for incidental * or consequential damages in connection with the furnishing, performance or * use of this material. * * This document contains proprietary information which is protected by * copyright. All rights reserved. No part of this document may be photocopied, * reproduced or translated to another language without the prior written * consent of SAP AG. * * */ import com.highdeal.iec.DataCollection; import com.highdeal.iec.UserLogger; public class ConsoleLogger implements UserLogger { public void init() { System.out.println("ConsoleLogger is initialized."); } public void close() { System.out.println("ConsoleLogger is closed."); } public void terminated(DataCollection dc, String actionUid) { System.out.println(dc.getUID()+" is terminated by "+actionUid); } public void rejected(DataCollection dc, String reasonCode, String[] args, String actionUid) { System.out.print(dc.getUID()+" is rejected by "+actionUid+� : "+reasonCode+"{"); int len; if (args!=null &amp;&amp; (len=args.length)>0){ System.out.print(args[0]); for (int i=1; i&lt;len; ++i){ System.out.print(", "); System.out.print(args[i]); } } System.out.println('}'); } public void filtered(DataCollection dc, String actionUid) { System.out.println(dc.getUID()+" is filtered by "+actionUid); } }

      This Documentation

      You can access online to the "Javadocs" of SAP Convergent Charging 2023 on SAP Help Portal at: help.sap.com/cc >> SAP CC 2023 >> Development Information.

      Recommendation

      Use always the more up-to-date version of this documentation. It is available in the following software unit of SAP CC: Software Development Kit (SDK) for the SAP CC Core Server. You can download all the SDKs from SAP Software Download Center (SWDC): Initial version or maintenance versions.

      Related Documentation

      For more information about the business and technical processes, see the SAP CC Application Help and the SAP CC Configuration Guide on SAP Help Portal at: help.sap.com/cc >> SAP CC 2023 >> Development:

      Other related documents can help you:

      • SAP CC IEC and CAT Tool Primary Help (SAP site) about the configuration of a scenario script in CAT Tool and about how to execute this scenario in an IEC application
        • Setting up a Java Action component
        • Setting up a Log Action component
        • Setting up a BART Acquisition Session component
        • Executing a scenario

      Other Java API References (for integration with other SAP CC systems)

      Additional Documentation

      Other Java API References (for integration with other SAP CC systems)

      Copyrights and Disclaimer

      (c) Copyright 2023 SAP SE or an SAP affiliate company. All rights reserved.

      No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company. The information contained herein may be changed without prior notice. Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors.

      All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary.

      These materials are subject to change without notice. These materials are provided by SAP SE and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

      Disclaimer

      This documentation may describe use cases that are not authorized for all customers in all regions. Please refer to your license agreement and comply with any territorial or use restrictions that apply.

      Some components of this product are based on Java. Any code change in these components may cause unpredictable and severe malfunctions and is therefore expressively prohibited, as is any decompilation of these components.

    Packages
    Package
    Description
    com.highdeal.iec
    This Java package specifies some useful Java interfaces and exceptions.
    com.highdeal.iec.action
    This Java package provides the JavaTask class and some Java interfaces to assign to your customized class when developing a Java class dedicated to customize the behavior of an SAP CC Import/Export Connector (IEC) application in your system landscape.
    com.highdeal.iec.hci
    This Java package provides the JavaActionModel class.