Oracle® Communications IP Service Activator

SDK Installation and Setup Guide

Release 7.4

E88205-01

December 2017

Oracle Communications IP Service Activator SDK Installation and Setup Guide, Release 7.4

E88205-01

Copyright © 2011, 2017, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.

Contents

Preface

- Related Documents

- Accessing Oracle Communications Documentation

- Online References

- Web References

- Documentation Accessibility

1 Installing the Software Development Kit

- About the SDK

- About the SDK Environment

- Third Party Tools and Versions

- Setting Environmental Variables

- Sample Commands to Set Windows Third Party Environment Variables

- Sample Commands to Set Solaris Third Party Environment Variables

- Installing the SDK

- Test Environments

- Upgrading an SDK Cartridge Installed on a Service Activator Host

- Upgrading an SDK Cartridge with a Service Activator Update

- Upgrading an SDK Cartridge without a Service Activator Update

- Uninstalling

- Uninstalling the SDK

- Deleting a Generated Cartridge or Configuration Policy From an SDK Host

- Uninstalling an SDK-generated Cartridge or Configuration Policy

- Converting Schema Names into Java

Preface

This guide explains how to install the Oracle Communications IP Service Activator Software Development Kit (SDK). It details the components and related environment for installing and running SDK tools. This guide provides details for installing, validating, and uninstalling the SDK.

Related Documents

For details about how to use the SDK to develop cartridges and configuration policies, refer to:

- IP Service Activator SDK Developer Overview Guide

- IP Service Activator SDK Base Cartridge Developer Guide

- IP Service Activator SDK Service Cartridge Developer Guide

- IP Service Activator SDK Configuration Policy Extension Developer Guide

Accessing Oracle Communications Documentation

IP Service Activator for Oracle Communications documentation, and additional Oracle documentation, is available from Oracle Help Center:

http://docs.oracle.com

Online References

Online references are included in the ipsaSDK-devGuides-versionString-sdk1.0.zip distribution file. See "Installing the SDK".

IP Service Activator Schema Online Documentation

An online reference is provided containing schema documentation which outlines how to populate and read XML instance documents used by the IP Service Activator Network Processor.

It is accessed through:

Service_Activator_home\ipsaSDK\doc\schemaDoc\index.html

IP Service Activator Configuration Policy Online Documentation

An online reference is provided documenting the Configuration Policies that are provided with the IP Service Activator core.

It is accessed through:

Service_Activator_home\ipsaSDK\doc\schemaDoc\configPolicyIndex.html

where Service_Activator_home is the directory to which IP Service Activator is deployed.

Web References

You can obtain the XML Schema Primer from the W3C, located at:

http://www.w3.org/TR/xmlschema-0/

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

1 Installing the Software Development Kit

This chapter explains how to install the Oracle Communications IP Service Activator Software Development Kit (SDK), how to install the required third-party utilities that support the SDK, and how to set up required environment variables.

About the SDK

The SDK is for developing cartridges and configuration policies. The cartridges are deployable into an IP Service Activator Network Processor installation, and the configuration policies are deployable into an IP Service Activator client installation.

Together, the developed cartridges and configuration policies extend the functionality of IP Service Activator. This can include, for example, support for additional services, and support for vendor devices not directly supported by the IP Service Activator product.

About the SDK Environment

The SDK is intended to be used on either a Windows-based or Oracle Solaris system. The documentation assumes that a Windows-based system is being used.

The SDK can run independently of IP Service Activator and Configuration Management. It does not need to be installed on a IP Service Activator or Configuration Management host. However, there may be some advantages to installing on a test IP Service Activator host, for example, to make it simpler to perform end-to-end testing.

Table 1-1 lists the placeholders used in this guide.

Table 1-1 SDK Directory Placeholders

Placeholder

Description

SDK_home

The directory in which the SDK is installed. This directory name as delivered is ipsaSDK.

Service_Activator_home

The directory to which IP Service Activator is deployed.

Examples giving paths are expressed with backslashes (&rsquor;\') to conform to Windows. If you are using Solaris, use forward slashes (&rsquor;/') in path names.

Third Party Tools and Versions

In order to use the SDK you must download and install the following third party utilities:

- Java Development Kit (JDK) version 1.7.x
Download from:

http://www.oracle.com/technetwork/java/javase/downloads/index.html

- Ant 1.6.2
Download the apache-ant-1.6.2-bin.zip file from:

http://archive.apache.org/dist/ant/binaries/

- JUnit 3.8.1
Download from:

http://sourceforge.net/projects/junit/files/junit/3.8.1/

Note:
After JUnit is installed, copy the junit.jar file to the ant library directory.
On Windows:

copy path_to_junit_install_dir\junit.jar path_to_ant_install_dir\lib

On Solaris:

cp path_tojunit_install_dir/junit.jar path_to_ant_install_dir/lib

- Saxon 8.8.0.7
Download:

http://sourceforge.net/projects/saxon/files/Saxon-B/8.8.0.7/

Note:
Ensure that you have the Saxon 8.8.0.7 release. The name of the .jar file (saxon8.jar) does not change with different sub-versions of Saxon 8.

- Velocity 1.4
Download from:

http://archive.apache.org/dist/velocity/engine/1.4/

If velocity1-4.zip is reported to be an invalid archive, download velocity1-4.tar.gz

Setting Environmental Variables

In order to run the SDK tools, certain environment variables must be set. If one of the third party tools cannot be located because an environment variable is not set correctly, you receive an error when you run Ant.

Note:
An existing CLASSPATH environment variable may interfere with the CLASSPATH required by the SDK. It is therefore recommended that the CLASSPATH environment variable be cleared/unset in the session where the SDK is being used.
For example, in Windows:

set CLASSPATH=

You can create a batch or script file to manually set up environment variables each time you are ready to work with the SDK, or you can adapt your system settings so that the environment variables are permanently configured.

The required environment variables include:

- PATH: must include paths to the ...\bin directories for Java and Ant

- JAVA_HOME: home directory of the JDK

- JUNIT: directory containing JUnit binaries

- ANT_HOME: directory containing Ant binaries

- SAXON: directory containing Saxon binaries

- VELOCITY: directory containing Velocity binaries

Sample Commands to Set Windows Third Party Environment Variables

The commands to configure the required environment variables from a Windows command line session are similar to the following example.

Note:
Replace SDK_home with the actual path to your SDK installation.

set CLASSPATH=
set JAVA_HOME=C:\Program Files\Java\jdk1.6.0_03
set ANT_HOME=C:\apache-ant-1.6.2
set JUNIT=C:\junit3.8.1
set SAXON=C:\saxonb-8.8.0.7
set VELOCITY=C:\velocity-1.4
set IPSA_SDK_HOME=SDK_home
set PATH=%JAVA_HOME%\bin;%ANT_HOME%\bin;%IPSA_SDK_HOME%\bin;%PATH%

Sample Commands to Set Solaris Third Party Environment Variables

The commands to configure the required environment variables on Solaris are similar to the following example.

Note:
Replace SDK_home with the actual path to your SDK installation.

unset CLASSPATH
export JAVA_HOME='/usr/jdk/1.6.0_03'
export ANT_HOME='/opt/apache-ant-1.6.2'
export JUNIT='/opt/junit3.8.1'
export SAXON='/opt/saxonb-8.8.0.7'
export VELOCITY='/opt/velocity-1.4'
export IPSA_SDK_HOME='SDK_home'
export PATH=$JAVA_HOME/bin:$ANT_HOME/bin:$IPSA_SDK_HOME/bin:$PATH

Installing the SDK

You can unzip the SDK files to any directory. If you have some IP Service Activator components already installed, it is acceptable, but not necessary to unzip the SDK files to the IP Service Activator directory (which the documentation refers to as Service_Activator_home).

The files will be copied to a new directory named ipsaSDK under the directory you select. For example, if you unzip the files to Service_Activator_home, the files will be placed under Service_Activator_home\ipsaSDK and Service_Activator_home\ipsaSDK will be referred to as SDKHome in the SDK documentation.

To install the SDK:

1. Install third party utilities as described in "Third Party Tools and Versions".

2. Ensure the SDK environment variables have been set up as described in "Setting Environmental Variables".

3. Download the IP Service Activator SDK from the Oracle software delivery website:
http://edelivery.oracle.com

The files to be installed are ipsaSDK-versionString-sdk1.0.zip and ipsaSDK-devGuides-versionString-sdk1.0.zip.

4. Unzip the SDK files to any directory.

Note:
The distribution file ipsaSDK-devGuides-versionString-sdk1.0.zip includes online references. See "Online References" for more information.

Test Environments

Basic tests of cartridges and configuration policies created with the SDK can be performed without an IP Service Activator or Configuration Management system.

To perform end-to-end tests of installed cartridges and configuration policies that you have developed, it is recommended that you have a Solaris-based IP Service Activator installation dedicated to the purpose. This system should have access to some actual devices.

It is not recommended to perform testing on a live IP Service Activator installation.

Upgrading an SDK Cartridge Installed on a Service Activator Host

The procedure for upgrading an SDK-based custom cartridge is impacted by the nature of the cartridge customization and its implementation.

If SDK-based custom cartridges and service extensions have been written in compliance with the upgrade interfaces in the SDK developer guides (configuration policy and service cartridge), the dbUpgrade and npUpgrade scripts will automatically upgrade SDK-based custom cartridges and service extensions.

It is strongly recommended that SDK developers adhere to these interfaces so that their upgrade is in line with the upgrade procedure given in this chapter.

Upgrading an SDK Cartridge with a Service Activator Update

To upgrade an SDK cartridge installed on a Service Activator host during an update:

1. Run npSnapshot on the old system.

2. Uninstall any old custom components, preserving required configuration files.

3. Uninstall the old system, preserving required configuration files.

4. Install the new system.

5. Install new custom components.

6. Integrate required configuration files from the old system.

7. Run dbupgrade.

8. Run npUpgrade.

Upgrading an SDK Cartridge without a Service Activator Update

To upgrade an SDK cartridge installed on a Service Activator host without an update:

1. Run npSnapshot on the old system.

2. Uninstall any old custom components, preserving required configuration files.

3. Install new custom components.

4. Integrate required configuration files from the old system.

5. Run npUpgrade with the –sdk option enabled.

Uninstalling

This section describes:

- How to uninstall the complete SDK

- How to delete individual SDK components (for example, a base cartridge, service cartridge, or configuration policy) from an SDK host

- How to uninstall SDK-generated cartridges or configuration policies deployed into a IP Service Activator installation

Uninstalling the SDK

Remove all sub-directories and files in the SDK_home directory.

Deleting a Generated Cartridge or Configuration Policy From an SDK Host

Cartridges and configuration policies reside in the following directories:

SDK_home/samples/baseCartridge/sdk_global_cartridgeName
SDK_home/samples/serviceCartridges/sdk_global_cartridgeName
SDK_home/samples/configPolicies/sdk_global_configPolicyName

Remove the specific cartridge or configuration policy directory you want to delete, including all of its files and sub-directories.

WARNING:

Generated cartridge or configuration policy files may have been customized after they were generated. Permanently deleting these files will result in the permanent loss of the customizations to the cartridge source files. Execute 'ant clean' in a cartridge directory, if instead of deleting the source files, your intent is to delete the files resulting from compilation of the cartridge.

Uninstalling an SDK-generated Cartridge or Configuration Policy

Each SDK cartridge or configuration policy contains a manifest file that lists all of the files packaged into its zip file. When a cartridge or configuration policy is installed on a IP Service Activator host, this manifest file is place into the Service_Activator_home/cartridgeUninstall directory.

Note:
For this topic, it is assumed that the cartridge or configuration policy has been deployed into a Solaris environment, so the instructions are in Solaris format instead of Windows format.

To uninstall an SDK cartridge or configuration policy from an IP Service Activator host:

1. Log in to a command shell on the IP Service Activator host where the SDK cartridge or configuration policy is installed.

2. Change directory to Service_Activator_home/cartridgeUninstall.
Note the manifest file name of the SDK cartridge or configuration policy that you want to remove. The file has one of the following formats:

- sdk_global_cartridgeName-baseCartridge-versionString.manifest

- sdk_global_configPolicyName-configPolicy-versionString.manifest

3. Change directory to Service_Activator_home.

4. Remove the cartridge or configuration policy by entering one of the following commands:

bin/uninstallCartridge.sh [-v] [-k] cartridgeUninstall/sdk_global_cartridgeName-baseCartridge-versionString.manifest

bin/uninstallCartridge.sh [-v] [-k] cartridgeUninstall/sdk_global_cartridgeName-serviceCartridge-versionString.manifest

bin/uninstallCartridge.sh [-v] [-k] cartridgeUninstall/sdk_global_configPolicyName-configPolicy-versionString.manifest

where the -v option provides extra output details about the uninstall operation and the -k option leaves intact any empty directories.

The script removes any files and directories used by this cartridge or configuration policy. Any directories that are shared with other cartridges or configuration policies are removed only if they are empty. With the -k option, empty directories are not removed.

The script also removes the cartridge or configuration policy manifest file.

5. Restart the network processor after the cartridge or configuration policy is uninstalled.

To remove the HTML for an SDK-generated configuration policy from an IP Service Activator client host:

1. Delete the HTML file in the Service_Activator_home/Config directory that is named after the configuration policy.

2. Remove the reference to the HTML file in the ConfigurationPolicy.cfg file. This consists of removing the object and policytype elements that refer to the configuration policy being removed. For example:

<GenericRule>
...
<object>
<policytypeReference ref=”banner”/>
</object>
...
<policytype name=”banner”>
<policyurl>file:///C:/ProgramFiles/Oracle Communications/IP Service Activator/Config/banner.html
</policyurl>
</policytype>
...
</GenericRule>

Both of these files are in the Service_Activator_home/Config directory.

Converting Schema Names into Java

When XMLbeans converts the schema name into Java, the algorithm used can sometimes incorrectly adapt it when there is a number in the schema. If this happens, you can use the xsdconfig file to override the default conversion.

To properly convert the schema name into Java:

1. Create a directory that contains the schema file.

2. Give that directory to the <xmlbeans> task.

3. Use the config policy sdk.

4. The xsdconfig file should be correctly generated by gencp.

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2017, Oracle and/or its affiliates. All rights reserved.

License Restrictions Warranty/Consequential Damages Disclaimer

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

Hazardous Applications Notice

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

Third-Party Content, Products, and Services Disclaimer

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.

Pre-General Availability Draft Documentation Notice

If this document is in public or private pre-General Availability status:

This documentation is in pre-General Availability status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.

Private Pre-General Availability Draft Documentation Notice

If this document is in private pre-General Availability status:

The information contained in this document is for informational sharing purposes only and should be considered in your capacity as a customer advisory board member or pursuant to your pre-General Availability trial agreement only. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described in this document remains at the sole discretion of Oracle.

This document in any form, software or printed matter, contains proprietary information that is the exclusive property of Oracle. Your access to and use of this confidential material is subject to the terms and conditions of your Oracle Master Agreement, Oracle License and Services Agreement, Oracle PartnerNetwork Agreement, Oracle distribution agreement, or other license agreement which has been executed by you and Oracle and with which you agree to comply. This document and information contained herein may not be disclosed, copied, reproduced, or distributed to anyone outside Oracle without prior written consent of Oracle. This document is not part of your license agreement nor can it be incorporated into any contractual agreement with Oracle or its subsidiaries or affiliates.

Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.