Oracle® Communications IP Service Activator SDK Installation and Setup Guide Release 7.2 E47720-01 |
|
|
PDF · Mobi · ePub |
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.
The SDK is used to develop 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.
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 (’\') to conform to Windows. If you are using Solaris, use forward slashes (’/') in path names.
In order to use the SDK you must download and install the following third party utilities:
Java Development Kit (JDK) version 1.6.0_03
Download from:
Ant 1.6.2
Download the apache-ant-1.6.2-bin.zip file from:
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
In order to run the SDK tools, certain environment variables must be set. If one of the third party tools can't be located because an environment variable is not set correctly, you'll 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
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%
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
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 is referred to in the documentation 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:
Install third party utilities as described in "Third Party Tools and Versions".
Ensure the SDK environment variables have been set up as described in "Setting Environmental Variables".
Download the IP Service Activator SDK from the Oracle software delivery Web site:
The files to be installed are ipsaSDK-VERSION_STRING-sdk1.0.zip and ipsaSDK-devGuides-VERSION_STRING-sdk1.0.zip.
Unzip the SDK files to any directory.
Note:
The distribution file ipsaSDK-devGuides-VERSION_STRING-sdk1.0.zip includes online references. See "Online References" for more information.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.
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 to comply with the upgrade interfaces in the SDK developer guides (configuration policy and service cartridge), then 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.
To upgrade an SDK cartridge installed on a Service Activator host:
Run npSnapshot on the old system.
Uninstall any old custom components, preserving required configuration files.
Uninstall the old system, preserving required configuration files.
Install the new system.
Install new custom components.
Integrate required configuration files from the old system.
Run dbupgrade.
Run npUpgrade.
This section describes:
How to uninstall the complete SDK
How to delete individual SDK components (i.e. 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
Cartridges and configuration policies reside in the following directories:
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.
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:
Log in to a command shell on the IP Service Activator host where the SDK cartridge or configuration policy is installed.
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
Change directory to Service_Activator_home.
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.
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:
Delete the HTML file in the Service_Activator_home/Config directory that is named after the configuration policy.
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.