3 Using the Eclipse Wizard

This section describes how to use the Eclipse Wizard to generate various extensions for Oracle Communications Services Gatekeeper (Services Gatekeeper).

About the Eclipse Wizard

The Eclipse Wizard is an Eclipse plug-in that streamlines the creation of a variety of Services Gatekeeper extensions. The extension projects are created using wizards that customize the project depending on which type of extension is being developed. You can create the following extensions:

• Communication Services

• Interceptor Modules

• OAuth2 Extension Handlers

• Platform Test Environment Custom Modules

• RESTful Communication Services

The Eclipse Wizard generates classes and Ant build files for both types of extensions, as well as a separate build file with Ant targets for packaging the extension for deployment.

Note:

The Communication Service Project(deprecated) wizard still exists for the sake of backwards compatibility. It is described in Using the Deprecated Communication Service Wizard, but its use is not recommended.

Configuring Eclipse

Before using Eclipse, you must configure it.

Prerequisites

• Eclipse 4.0 or higher version must be installed.

• OCSG version 5.1 or higher must be installed.

Basic configuration of Eclipse environment

To do the basic configuration of the Eclipse environment:

1. Start Eclipse.

2. Open the Preferences window, Window −> Preferences...

3. In Java−>Installed JREs, make sure that the JRE used is the JRE installed with OCSG. This is installed in Middleware_Home/jdk_version/jre.

Configuring the Eclipse Wizard

To configure the Eclipse Wizard, do the following:

1. Start Eclipse.

2. Open the Preferences window, Window−>Preferences...

3. In OCSG Platform Development Studio, configure the following:

   Middleware Home Directory The directory of the Oracle Communications Services Gatekeeper installation. This provides references to WebLogic Server APIs. In the default installation, this would be Middleware_Home.

   JDK Installation Directory The JDK installation directory for Oracle Communications Services Gatekeeper, for example Middleware_Home/jdk160_29b11.

   Logging Level The logging level of the Eclipse plug-in and the Ant tasks. Determines what level of detail to log by Eclipse. Select All for detailed logs, Standard for less detailed logs.

Generating a Communication Service Project

This section describes how to generate a communication service project.

A Communication Service project is based on a WSDL file and a set of attributes given when running the Communication Service Project wizard. Both RESTful and SOAP facades are generated from the provided WSDLs.

The WSDL defining the application-facing interface must adhere to the following:

• The attribute name in <wsdl:service> must include the suffix Service.

• The attribute name in <wsdl:port> must be the same as the name attribute in <wsdl:service>, excluding the suffix Service.

To generate a Communication Service project:

1. In Eclipse, choose File then New Project.

   This opens the New Project window.

Table 3-1 Communication Service Wizard Tasks

In this window...	Perform the following action...
Select a wizard	Make sure OCSG Platform Development Studio−>Communication Service Project is selected. Click Next to proceed. You may cancel the wizard at any time by clicking Exit. You may go back to a previous window by clicking Previous.
Create a Communication Service	Enter a Project Name and choose a location for your project. Click Next to continue.
Define the Communication Service Configure Service WSDL Files	For each WSDL file that includes the service definition to be implemented by the new Communication Service: Click the Add button Description of the illustration addel.png In the WSDL Configuration dialog, click the Add button adjacent the WSDL File text box, browse to the WSDL file, select it, and click OK. Choose to use either a custom REST configuration file by clicking the Add button adjacent the Use custom file text box, or have the wizard generate a configuration file by clicking the Generate button adjacent the Generate config file radio button. If you choose to have the wizard generate a rest-config.xml file for you, you should make any changes to the file before continuing. Click OK.
Define the Communication Service Configure Callback WSDL Files	For each WSDL file that includes the callback service definition to be used by the new Communication Service in sending information to the service provider's application: Click the Add button. Description of the illustration addel.png In the WSDL Configuration dialog, click the Add button adjacent the WSDL File text box, browse to the WSDL file, select it, and click OK. Choose to use either a custom REST configuration file by clicking the Add button adjacent the Use custom file text box, or have the wizard generate a configuration file by clicking the Generate button adjacent the Generate config file radio button. If you choose to have the wizard generate a rest-config.xml file for you, you should make any changes to the file before continuing. Click OK.
Define the Communication Service Communication Service Properties	Company: Set your company name, to be used in META-INF/MANIFEST.MF. Version: Set the version, to be used in META-INF/MANIFEST.MF. Identifier: Create an identifier to tie together a collection of Web Services. This identifier will be a part of the names of the generated war and jar files and the service type for the Communication Service: communication_service_identifier.war and communication service identifier_callback.jar Service Type: Set the service type. Used in EDRs, statistics, and others. For example: SmsServiceType, MultimediaMessagingServiceType.
Define the Communication Service SOAP Properties tab	SOAP Class Package Name: The package name you wish to use for the SOAP communication service. Must adhere to standard Java naming conventions. Web Services Context Path: The base HTTP path for the SOAP web service. Handler File: A customized SOAP handler chain. If not provided, the default handler is used.
Define the Communication Service REST Properties tab	RESTful Class Package Name: The package name you wish to use for the REST communication service. Must adhere to standard Java naming conventions. RESTful Context Path: The base HTTP path for the RESTful web service. RESTful Source Directory: A directory containing additional sources that will be compiled into war/APP-INF/classes. This directory is only used for the application tier. RESTful Handler Chain: A customized RESTful handler chain. If not specified, the default handler chain will be used, including those for x-param, URL, session-id, authorizationHeader, and others. JAXRS Application Class: An optional JAX-RS application class that defines resources and additional metadata. For more information, see chapter two in the JSR-000311 JAX-RS: The JavaTM API for RESTful Web Services 1.0 Final Release specification: http://download.oracle.com/otndocs/jcp/jaxrs-1.0-fr-eval-oth-JSpec/. JAXRS Context Resolver Class: An optional JAX-RS class that provides context information to resource classes in addition to other providers. For more information, see chapter three of the JSR-000311 JAX-RS: The JavaTM API for RESTful Web Services 1.0 Final Release specification: http://download.oracle.com/otndocs/jcp/jaxrs-1.0-fr-eval-oth-JSpec/. JAXRS Exception Mapper Classes: An optional JAX-RS class that maps Java exceptions to standard HTTP responses. For more information, see chapter five of the JSR-000311 JAX-RS: The JavaTM API for RESTful Web Services 1.0 Final Release specification: http://download.oracle.com/otndocs/jcp/jaxrs-1.0-fr-eval-oth-JSpec/. Support Attachment: If checked the service will support attachments in both requests and responses. Click Next to continue.
Define the plug-in information	For each plug-in to be created in the Communication Service project: This opens a pop-up window with the following fields: Protocol: An identifier for the network protocol the plug-in implements. Used as a part of the names of the generated jar file: communication_service_identifier._protocol.jar and the service name Plugin_communication_service_identifier._protocol Schemes: Address schemes the plug-in can handle. Use a comma separated list if multiple schemes are supported. For example: tel or sip Package Name: Package names to be used. Company: Used in META-INF/MANIFEST.MF. Version: Used in META-INF/MANIFEST.MF. SOAP to SOAP: Select to this check-box to generate a plug-in for a SOAP to SOAP Communication Service. REST to REST: Select to this check-box to generate a plug-in for a REST to REST Communication Service. Click Finish to start the code generation for the plug_in(s).

Generating an Interceptor Module

This section describes how to generate an interceptor module project.

To generate an interceptor module project:

1. In Eclipse, choose File −> New −> Other.

   This opens the Select a wizard window.

Table 3-2 Interceptor Module Wizard Tasks

In this window...	Perform the following action...
Select a wizard	Make sure OCSG Platform Development Studio −> Interceptor Module is selected. Click Next to proceed. You may cancel the wizard at any time by clicking Exit. You may go back to a previous window by clicking Back.
Generate Interceptor modules	Enter a Project name for your project. Select either Use default location or click Browse to choose a new location for your project. In the Package Name text box, enter a package name. In the Application Lifecycle Listener text box, enter an optional lifecycle listener. Click the Add button to an interceptor: Description of the illustration addel.png
Add Interceptor	For each interceptor you want to configure, enter the following information: Name: the name of the interceptor. Index: the index of the interceptor. Point: the point in Services Gatekeeper where the interceptor will intercept events. You can choose from: MO North MO South MT North MT South
Generate Interceptor modules	You can add additional interceptors by clicking the Add button and entering the required information in the Add Interceptor dialog. Click Finish to start the code generation for the interceptor(s).

Generating an OAuth 2.0 Extension Handler

This section describes how to generate an OAuth 2.0 extension handler.

To generate an OAuth 2.0 extension handler project:

1. In Eclipse, choose File −> New −> Other.

   This opens the Select a wizard window.

Table 3-3 OAuth 2.0 Extension Handler Wizard Tasks

In this window...	Perform the following action...
Select a wizard	Make sure OCSG Platform Development Studio −> OAuth2 Extension Handlers is selected. Click Next to proceed. You may cancel the wizard at any time by clicking Exit. You may go back to a previous window by clicking Back.
Generate OAuth2 Extended Handlers	Enter a Project name for your project. Select either Use default location or click Browse to choose a new location for your project. In the Package Name text box, enter a package name. Click the Add button to a handler: Description of the illustration addel.png
Add Handler	For each handler you want to configure, enter the following information: Handler Name: the name of the OAuth2 handler. Select Ext if you want to add more extensive customization for the handler. Validator Name: the name of the validator for the OAuth2 handler. ResponseType: the type of response the validator expects: code token GrantType: the type of grant type the validator expects: authorization_code refresh_token password client_credentials Click OK to add the new validator.
Generate Interceptor modules	You can add additional handlers by clicking the Add button and entering the required information in the Add Handler dialog. Click Finish to start the code generation for the handler(s).

Generating a Platform Test Environment Custom Module

To generate a Platform Test Environment custom module project:

1. In Eclipse, choose File −> New −> Other.

   This opens the Select a wizard window.

Table 3-4 Platform Test Environment Custom Module Wizard Tasks

In this window...	Perform the following action...
Select a wizard	Make sure OCSG Platform Development Studio −> PTE Custom Module is selected. Click Next to proceed. You may cancel the wizard at any time by clicking Exit. You may go back to a previous window by clicking Back.
Generate PTE modules	Enter a Project name for your project. Select either Use default location or click Browse to choose a new location for your project. Choose one of the following options: Use custom WSDL files: creates a PTE module based upon a WSDL file that you specify. Continue to Generate PTE modules / Use custom WSDL files below. Use predefined WSDL files: creates a PTE module based upon a pre-existing Services Gatekeeper application interface. Continue to Generate PTE modules / Use predefined WSDL files below. Use WADL: creates a PTE module based upon a WADL file that you provide. Generate PTE modules / Continue to Use WADL below. Rest2Rest WADL: creates a PTE module based upon a Rest2Rest WADL file that you provide. Continue to Generate PTE modules / Rest2Rest WADL below.
Generate PTE modules / Use custom WSDL files	In Configure Service WSDL Files, for each WSDL file that includes a service definition to be implemented by the new PTE module: Click the Add button Description of the illustration addel.png In the WSDL Configuration dialog, click the Add button adjacent the WSDL File text box, browse to the WSDL file, select it, and click OK. Optionally, click the Add button to add one or more JAX-WS or JAXB binding files to your project. Click OK. In Configure Callback WSDL Files, for each WSDL file that includes a callback service definition to be used by the new PTE module to return information to the service provider's application: Click the Add button. Description of the illustration addel.png In the WSDL Configuration dialog, click the Add button adjacent the WSDL File text box, browse to the WSDL file, select it, and click OK. Optionally, click the Add button to add one or more JAX-WS or JAXB binding files to your project. Click OK.
Use PTE modules / Use predefined WSDL files	Choose one of the following predefined communication services: px30_audio_call px21_call_notification px30_call_notification px21_multimedia_messaging px21_presence ews_push_message px21_sms ews_binary_sms ews_subscriber_profile px21_terminal_location px21_third_party_call px30_third_party_call px30_payment Continue to Settings below.
Generate PTE modules / Use WADL	In Configure Service WADL Files, for each WADL file that includes a service definition to be implemented by the new PTE module: Click the Add button Description of the illustration addel.png In the WADL Files Configuration dialog, click the Add button, browse to the WADL file, select it, and click OK. Click OK. Continue to Generate PTE modules / Settings.
Generate PTE modules / Use Rest2Rest WADL	In Configure Service WADL Files, for each WADL file that includes a service definition to be implemented by the new PTE module: Click the Add button Description of the illustration addel.png In the WADL Files Configuration dialog, click the Add button, browse to the WADL file, select it, and click OK. Click OK. Continue to Generate PTE modules / Settings.
Generate PTE modules / Settings	In Settings, enter the following information: Name: a name for the PTE module. Package Name: a Java package name that will contain the package classes. Company: your company name, used in META-INF/MANIFEST.MF. Version: the version, used in META-INF/MANIFEST.MF. Click Finish to generate the PTE module handler.

Generating a RESTful Communication Service Project

Service providers may have existing third-party or proprietary applications or platforms that communicate using REST web services. Services Gatekeeper functionality can be integrated with existing applications that support REST interfaces by creating a RESTFul communication service.

Services Gatekeeper supports two types of RESTFul communication services. A REST to REST service exposes an existing REST API allowing communication between RESTFul interfaces. A REST Exposure or empty service is an application bound, network-facing service used when RESTFul requests are sent to a custom network implementation for translation and processing.

Services Gatekeeper mediates traffic between users and existing REST infrastructure allowing the application of service level agreements, policy enforcement, security, alarms and statistics for more control over communication services.

For more information on communication services, see Communication Service Guide.

The Eclipse RESTful Communication Service Project wizard generates REST communication services from Web Application Description Language (WADL) files representing RESTFul web application services. Services Gatekeeper then uses the generated service to handle RESTFul communications between two platforms.

The Eclipse wizard is used to create both REST2REST and REST Exposure services.

To generate a RESTful communication service project:

1. In Eclipse, choose File −> New −> Other.

   This opens the Select a wizard window.

Table 3-5 RESTful Communication Service Project Wizard Tasks

In this window...	Perform the following action...
Select a wizard	Make sure OCSG Platform Development Studio −> RESTFul Communication Service Project is selected. Click Next to proceed. You may cancel the wizard at any time by clicking Exit. You may go back to a previous window by clicking Previous.
Create a RESTFul Communication Service	Enter a Project Name and choose a location for your project. Click Next to continue.
Define the RESTFul Communication Service	For each WADL file that includes the service definition to be implemented by the new Communication Service: Click the Add button Description of the illustration addel.png Browse to the WADL file, select it, and click OK. To select all WADL files in a directory use *.wadl
Define the RESTFul Communication Service	For each WADL file that includes the callback service definition to be used by the new Communication Service in sending information to the service provider's application: Click the add button, browse to the WADL file, select it, and click OK.
RESTFul Communication Service Properties	Company: Set your company name, to be used in META-INF/MANIFEST.MF. Version: Set the version, to be used in META-INF/MANIFEST.MF. Identifier: Create an identifier to tie together a collection of Web Services. Will be a part of the names of the generated war and jar files and the service type for the Communication Service: communication_service_identifier.war and communication service identifier_callback.jar Service Type: Set the service type. Used in EDRs, statistics, etc. For example: Rest2RestXsi_Actions. Java Class Package Name: Set the package names to be used. For example: oracle.ocsg.rest2rest Web Services Context path: Set the context path for the Web Service.For example: /xsi_actions Source Directory: A directory containing additional sources that will be compiled into war/APP-INF/classes. This directory is only used for the application tier. RESTful Handler Chain: A customized RESTful handler chain. If not specified, the default handler chain will be used, including those for x-param, URL, session-id, authorizationHeader, and others. JAXRS Application Class: An optional JAX-RS application class that defines resources and additional metadata. For more information, see chapter two in the JSR-000311 JAX-RS: The JavaTM API for RESTful Web Services 1.0 Final Release specification: http://download.oracle.com/otndocs/jcp/jaxrs-1.0-fr-eval-oth-JSpec/. JAXRS Context Resolver Class: An optional JAX-RS class that provides context information to resource classes in addition to other providers. For more information, see chapter three of the JSR-000311 JAX-RS: The JavaTM API for RESTful Web Services 1.0 Final Release specification: http://download.oracle.com/otndocs/jcp/jaxrs-1.0-fr-eval-oth-JSpec/. JAXRS Exception Mapper Classes: An optional JAX-RS class that maps Java exceptions to standard HTTP responses. For more information, see chapter five of the JSR-000311 JAX-RS: The JavaTM API for RESTful Web Services 1.0 Final Release specification: http://download.oracle.com/otndocs/jcp/jaxrs-1.0-fr-eval-oth-JSpec/. Support Attachment: If checked the service will support attachments in both requests and responses. REST to REST: Check this box to generate a Rest2Rest Communication Service. Click Next to continue to the Define the plugin information window or Finish if you are ready to create the project.
Define the plugin information	A list of plug-ins defined for the project is displayed. For each plug-in to be created in the project: Click the add plug-in button: Description of the illustration addplugin.png This opens a pop-up window with the following fields: Protocol: An identifier for the network protocol the plug-in implements. Used as a part of the names of the generated jar file: communication_service_identifier._protocol.jar and the service name Plugin_communication_service_identifier._protocol Schemes: Address schemes the plug-in can handle. Use a comma separated list if multiple schemes are supported. For example: tel or sip Package Name: Package names to be used. Company: Used in META-INF/MANIFEST.MF. Version: Used in META-INF/MANIFEST.MF. Choose which Type of plug-in to generate: REST: Select to this radio-button to generate a generic, protocol-neutral, RESTful plug-in. SIP: select to this radio-button to generate a plug-in that connects to a SIP network using a SIP Servlet. Click OK. The plug-in definitions are added to the list of plug-ins. Click Finish to create the project.

Communication Service Wizard-generated OAM Attributes

The Communication Service and RESTFul Communication Service wizards, generate the following OAM attributes in <Project_Name>/<Identifier>/plugins/protocol/src/<Plugin_Package_Name>.management/<Service_Type>MBean.java:

• ServerUrl: The URL of the REST server

• ProxyHost: The outbound HTTP proxy host

• ProxyPort: The outbound HTTP proxy port

• CallbackServerUrl: The URL of the REST callback server

• CallbackProxyHost: The outbound HTTP proxy host of the mobile originating request

• CallbackProxyPort: The outbound HTTP proxy port of the mobile originating request

• CallbackUserName: The application instance name of the mobile originating request

• CallbackUserPassword: The password for the application instance name of the mobile originating request

Note:

The values for ServerUrl and CallbackServerUrl are not pulled from the source WADL files and are, instead, set to http://xsp2.xdp.broadsoft.com. You must update those values manually after the project has been generated.

Adding and Removing Plug-ins

This section describes how to add plug-ins to and remove plug-ins from a communication service project.

Adding a Plug-in to a Services Gatekeeper Project

To add a plug-in to an existing Services Gatekeeper project:

1. In the Eclipse package explorer, right-click the project for the Services Gatekeeper project, and choose Properties.

   This opens the Properties window for the Services Gatekeeper project.

Table 3-6 Add Plug-in Configuration Tasks

In this window...

Perform the following action...

Plugin Configuration

A list of plug-ins defined for the project is displayed. For each plug-in to be created in the project: Click the add plug-in button: Description of the illustration addplugin.png This opens a pop-up window with the following fields: Protocol: An identifier for the network protocol the plug-in implements. Used as a part of the names of the generated jar file: communication_service_identifier._protocol.jar and the service name Plugin_communication_service_identifier._protocol Schemes: Address schemes the plug-in can handle. Use a comma separated list if multiple schemes are supported. For example: tel or sip Package Name: Package names to be used. Company: Used in META-INF/MANIFEST.MF. Version: Used in META-INF/MANIFEST.MF. Choose which Type of plug-in to generate: SOAP: Select to this radio-button to generate a generic, protocol-neutral, plug-in. SOAP to SOAP: Select to this radio-button to generate a plug-in for a SOAP to SOAP Communication Service. SIP: select to this radio-button to generate a plug-in that connects to a SIP network using a SIP Servlet. Click OK. The plug-in definitions are added to the list of plug-ins. Click Finish to start the code generation for the plug-in(s).

Removing a Plug-in from a Communication Service Project

To remove a a plug-in from an existing Communication Service project:

1. In the Eclipse package explorer, right-click the project for the Communication Service project, and choose Properties.

   This opens the Properties Window for the Communication Service project.

   Table 3-7 Remove plug-in configuration task

   In this window...

   Perform the following action...

   Plugin Configuration

   A list of plug-ins defined for the Communication Service project is displayed. For each plug-in to be removed from the Communication Service project: Select the plug-in to be removed. Click the remove plug-in button: Description of the illustration removeplugin.png The plug-in definitions are removed from the list. Click Apply to remove the plug-in part(s) from the Communication Service project. Warning: This removes all parts of the project, including any manually edited or added files. Click Restore Defaults to restore the plug-in definition list.

   
   

2. Click OK or Cancel to close the Properties window.

Using the Deprecated Communication Service Wizard

This section describes how to generate a communication service project using the deprecated communication service wizard.

Caution:

This wizard has been deprecated in favor of the wizard documented here Generating a Communication Service Project.

A Communication Service project is based on a WSDL file and a set of attributes given when running the Communication Service Project(deprecated) wizard.

The WSDL defining the application-facing interface must adhere to the following:

• Attribute name in <wsdl:service> must include the suffix Service.

• Attribute name in <wsdl:port> must be the same as the name attribute in <wsdl:service>, excluding the suffix Service.

To generate a Communication Service project:

1. In Eclipse, choose File−>New Project.

   This opens the New Project window.

Table 3-8 Communication Service Wizard(deprecated) Tasks

In this window...	Perform the following action...
Select Wizard	Make sure OCSG Platform Development Studio−>Communication Service Project(deprecated) is selected. Click Next to proceed. You may cancel the wizard at any time by clicking Exit. You may go back to a previous window by clicking Previous.
Create a Communication Service	Enter a Project Name and choose a location for your project. You can choose: To create an entirely new Communication Service To create a new Service Facade (application-facing interface) and the common parts of the Service Enabler layer for an existing plug-in To create a new network plug-in that uses the Service Facade and common parts of the Service Enabler of a currently existing Communication Service. If you wish to do 3, check the check-box Use predefined communication service and from the drop-down list select the Service Facade for which you want to create a plug-in. If you wish to do 1 or 2, leave the box unchecked. Click Next to continue. If you checked the Use predefined check box, the Define the Plug-in Information window is displayed. Go to Define the Plug-in Information instructions below. If you did not check it, the Define the Communication Service is displayed.
Define the Communication Service / Configure Service WSDL Files	For each WSDL file that includes the service definition to be implemented by the new Communication Service: Click the Add button Description of the illustration addel.png Browse to the WSDL file, select it, and click OK.
Define the Communication Service Configure Callback WSDL Files	For each WSDL file that includes the callback service definition to be used by the new Communication Service in sending information to the service provider's application: Click the add button, browse to the WSDL file, select it, and click OK.
Define the Communication Service Communication Service Properties	Company: Set your company name, to be used in META-INF/MANIFEST.MF. Version: Set the version, to be used in META-INF/MANIFEST.MF. Identifier: Create an identifier to tie together a collection of Web Services. Will be a part of the names of the generated war and jar files and the service type for the Communication Service: communication_service_identifier.war and communication service identifier_callback.jar Service Type: Set the service type. Used in EDRs, statistics, etc. For example: SmsServiceType, MultimediaMessagingServiceType. Java Class Package Name: Set the package names to be used. For example: com.mycompany.service Web Services Context path: Set the context path for the Web Service.For example: myService SOAP to SOAP: Check this box to generate a Service Facade that can be a part of a SOAP to SOAP Communication Service. REST: Check this box to generate a RESTful Service Facade for the Communication Service.
Define the Plug-in information	For each plug-in to be created in the Communication Service project: Click the add plug-in button Description of the illustration addplugin.png This opens a pop-up window with the following fields: Protocol: An identifier for the network protocol the plug-in implements. Used as a part of the names of the generated jar file: communication_service_identifier._protocol.jar and the service name Plugin_communication_service_identifier._protocol Schemes: Address schemes the plug-in can handle. Use a comma separated list if multiple schemes are supported. For example: tel: or sip: Package Name: Package names to be used. Company: Used in META-INF/MANIFEST.MF. Version: Used in META-INF/MANIFEST.MF. Choose which Type of plug-in to generate: SOAP: Select to this radio-button to generate a generic, protocol-neutral, plug-in. SOAP to SOAP: Select to this radio-button to generate a plug-in for a SOAP to SOAP Communication Service. SIP: select to this radio-button to generate a plug-in that connects to a SIP network using a SIP Servlet. Click OK. The plug-in definitions are added to the list of plug-ins. Click Finish to start the code generation for the plug_in(s).