Apache Tuscany : SCA Java binding.corba

+ + +

+

General

+

Home
+License
+Get Involved
+Found a Bug?

+

+ +

SCA Java

+

SCA Java Home
+SCA Dashboard
+Tools
+FAQ

+

+ +

SCA Java 1.x

+

Downloads
+Documentation
+1.x Source Code
+Roadmap

+

+ +

SCA Java 2.x

+

Downloads
+Documentation
+2.x Source Code
+Roadmap

+

+ + +

Documentation

+

User Guide
+Architecture Guide
+Developer Guide
+Extension Developer Guide

+

+ +

Resources

+

FAQ
+Source Code

+

+ +

<binding.corba>

+ +

The Tuscany Java SCA runtime supports CORBA using the <binding.corba> SCDL extension. New CORBA based service can be provided using a <binding.corba> element within a SCA <service>, existing CORBA object can be accessed using a <binding.corba> element within a SCA <reference>.

+

Configuring CORBA service/reference
Providing interface
CORBA arrays and unions mapping
Methods to operations mapping
Usage of additional "id" attribute in CORBA service bindings
Host environment types

+ + +

Using CORBA binding

+ +

Configuring CORBA service/reference

+ +

Location for both service and reference CORBA binding can be configured by:

+ +

1. Name, host, port parameters, where host and port points to name service, and name points to object within name service.

+ +

Example service declaration:

+

<service name="ScenarionOneServiceGenerated" promote="ScenarionOneServiceGenerated">
+
+    <interface.java interface="org.apache.tuscany.sca.test.corba.generated.ScenarioOneOperations"/>
+
+    <tuscany:binding.corba host="localhost" port="5060" name="ScenarioOne/TuscanyGenerated"/>
+
+</service>
+

+

2. Corbaname URI.

+ +

Example reference declaration:

+

<reference name="scenarioOne">
+
+    <tuscany:binding.corba uri="corbaname::localhost:5060#NamedWithURI"/>
+
+</reference>
+

+

+ +

Providing interface

+ +

For both service and reference side you can use one of two types of Java interface:

+ +

1. Generated by idlj compiler from *.idl file.

+ +

2. Created by user according to rules for Java to CORBA mapping.

+ +

In both cases interfaces are almost the same. Difference is that generated interfaces extends/implements CORBA types which are ignored by binding. Mapping rules are available under: Java2IDL, IDL2Java. Samples of CORBA bindings can be found in sca/itest/corba module.
+

+

Overloading, case collisions
When using Tuscany service/reference binding to communicate with traditional CORBA objects: + +

1. Don't overload method names in Java interface.

+ +

2. Don't create methods with names which differs only by case, ie. you shouldn't declare both methods: caseSensitive() and CaseSensitive().

+ +

You can ignore above rules if you are using Tuscany CORBA binding to communicate with other Tuscany CORBA binding. Those constraints results from differences between IDL and Java. More details can be found in Method/operation mapping rules section.

+

Declaring exceptions
Exceptions declared by user should be named to match remote exception ID. + +

Example: if in reference binding remote object throws exception with ID "IDL:org/apache/tuscany/sca/test/corba/generated/WrongColor:1.0" then you should declare exception class named "org.apache.tuscany.sca.test.corba.generated.WrongColor".

+ +

The same in service bindings. SCA component exception will be thrown with ID created from Java name.

+

+ +

CORBA arrays and unions mapping

+ +

CORBA arrays and unions cannot be directly mapped so additional metadata should be used.

+ +

1. Arrays mapping

+ +

To declare CORBA array you should declare Java array and annotate it by org.apache.tuscany.sca.binding.corba.meta.CorbaArray annotation.

+ +

Annotation org.apache.tuscany.sca.binding.corba.meta.CorbaArray has one default attribute (array of integers) which declares lengths of following array dimensions. Objects you can annotate are:

+

binding interface methods arguments
binding interface methods, which will refer to return type
structure fields

+ + +

Example:

+

import org.apache.tuscany.sca.binding.corba.meta.CorbaArray;
+
+public interface SampleInterface {
+
+    @CorbaArray( {2, 2}) // this annotation makes return array to be CORBA array
+    public String[][] passStringArray(@CorbaArray( {2, 2})String[][] arg); // this annotation makes mehods argument to be CORBA array
+
+}
+

+

You can also annotate fields in CORBA structures.

+ +

Example:

+

import org.apache.tuscany.sca.binding.corba.meta.CorbaArray;
+
+public final class SampleStruct {
+
+    @CorbaArray( {2, 2}) // following field is two dimensional CORBA array, which has 2 elements in both first and second dimension
+    public String[][] stringArray;
+
+    public SampleStruct() {
+
+    }
+
+    public SampleStruct(String[][] stringArray) {
+        this.stringArray = stringArray;
+    }
+
+}
+

+

2. Unions mapping

+ +

To declare CORBA union you should create final Java class which contains:

+

private field for every union option
private field of int, which will be discriminator

+ + +

Union options as well as discriminator should be annotated with org.apache.tuscany.sca.binding.corba.meta.CorbaUnionElement, which has two attributes:

+

CorbaUnionElementType type(), which can take following values: +
- CorbaUnionElementType.option for member, additional optionNumber attribute is required
- CorbaUnionElementType.defaultOption for default union member
- CorbaUnionElementType.discriminator for discriminator field
+
int optionNumber() - can be used only with CorbaUnionElementType.option

+ + +

Example:

+ +

Following IDL declaration:

+

union SampleUnion switch (long) {
+    case 1: long x;
+    case 2: float y;
+    default: string z;
+};
+

+

is equal to Tuscany CORBA binding declaration:

+

import org.apache.tuscany.sca.binding.corba.meta.CorbaUnionElement;
+import org.apache.tuscany.sca.binding.corba.meta.CorbaUnionElementType;
+
+public final class SampleUnion {
+
+    @CorbaUnionElement(type = CorbaUnionElementType.option, optionNumber = 1)
+    // this is union member, id = 1
+    private int x;
+
+    @CorbaUnionElement(type = CorbaUnionElementType.option, optionNumber = 2)
+    // this is union member, id = 2
+    private float y;
+
+    @CorbaUnionElement(type = CorbaUnionElementType.defaultOption)
+    // this is default union member
+    private String z;
+
+    @CorbaUnionElement(type = CorbaUnionElementType.discriminator)
+    private int discriminator;
+
+    public int getX() {
+        return x;
+    }
+
+    public void setX(int x) {
+        discriminator = 1;
+        this.x = x;
+    }
+
+    public float getY() {
+        return y;
+    }
+
+    public void setY(float y) {
+        discriminator = 2;
+        this.y = y;
+    }
+
+    public float getZ() {
+        return z;
+    }
+
+    public void setZ(float z) {
+        discriminator = -1;
+        this.z = z;
+    }
+
+}
+

+

+ +

Method/operation mapping rules

+ +

IDL rules are different than rules in Java programming language - Java method names can't be always directly mapped to CORBA operations. Following table shows used mapping rules:

+

+ + + + + + + + + + + + + + + + + + + + + +

Mapping type	Description	Examples: Java method - translated CORBA operation
1. Getters and setters	If user declared valid pair of getter and setter then those methods wouldbe translated to operations which are responsible for getting/setting objects attribute.	1. getName() - _get_name +2. setName(String newName) - _set_name +3. isName() - _get_name
2. Overloaded names	CORBA does not support overloading method names - Java does.. Some mapping rules were applied to allow using overloaded names in Java interfaces using CORBA binding. Final operation name is created by taking method name and appending it by CORBA parameters type names separated by '_' chars.	1. overloadedMethod() - overloadedMethod__ +2. overloadedMethod(String arg1) - overloadedMethod__CORBA_WStringValue +3. overloadedMethod(String arg1, int arg2) - overloadedMethod_CORBA_WStringValue_long
3. Names with case collisions	CORBA is not case sensitive - Java is. CORBA ie. doesn't distinguish methods caseDifferent() and CaseDifferent(), so some mapping rules are fixing it. Final operation name is created by taking method name and appending it by indexes of characters which are capitals.	1. caseDifferent() - caseDifferent_4 +2. CaseDifferent() - CaseDifferent_0_4

+

+ +

Usage of additional "id" attribute in CORBA service bindings

+ +

User can also provide id attribute for service binding. It's not required, but helpfull if we want to publish service which will be consumed by some idlj generated code. This generated code contains *Helper classes with narrow(...) methods. Narrow(...) method compares obtained CORBA reference ID to some local (which was generated). CORBA service binding provide this ID automatically basing on user provided Java interface name. Providing id attribute is the only way to provide custom identifier.

+ +

Example of using "id" attribute:

+

<service name="ScenarionOneServiceGenerated" promote="ScenarionOneServiceGenerated">
+
+    <interface.java interface="org.apache.tuscany.sca.test.corba.generated.ScenarioOneOperations"/>
+
+    <tuscany:binding.corba host="localhost" port="5060" name="ScenarioOneTuscanyGenerated"
+                           id="IDL:org/apache/tuscany/sca/test/corba/generated/ScenarioOne:1.0"/>
+
+</service>
+

+

+ +

Host environment types

+ +

CORBA binding supports two hosting environments.

+ +

host-corba-jse

+ +

It is the standalone hosting environment where various ORBs could be used. Note that you have to provide name service by yourself and configure service/reference to point onto desired ORB.
+ Usage: add tuscany-host-jse-<version>.jar module to your class path.

+ +

host-corba-jse-tns

+ +

Not available in official Apache Tuscany release

+ + +

This hosting environment extends host-corba-jse. For every configured service CORBA binding which points to localhost Transient Name Service will be created and name servers for bindings using the same port will be shared.
+ Usage: add tuscany-host-jse-tns-<version>.jar module to your class path.

+ +

host-corba-jee

+ +

Not available in official Apache Tuscany release

+ + +

It is the JEE application server environment. In this case ORB is obtained from JNDI by java:comp/ORB name and you don't need to provide name service. Also host and port (or their equivalent contained in corbaname URI) parameters are ignored.
+ Usage: add tuscany-host-jee-<version>.jar module to your class path.

+