Using XMLink Universal Gateway

Chapter 6. Writing Enterprise Services

This chapter describes information needed to write enterprise services using the Java class XugReturn in the com.prolifics.tconn.server package. This class returns a specific return value and user return code to the Tuxedo client.

XugReturn is a Java bean with two int properties, rval and rcode. The constructor takes rval as the first parameter, and rcode as the second.

Set rval to one of the following public static final members of XugReturn:

The Gateway Tuxedo Server will return TPEXIT, TPFAIL, or TPSUCCESS respectively. Return data is available to the Tuxedo client, regardless of which return value is used.

rcode may be set to any desired value. Have the Tuxedo client use tpurcode() in the Tuxedo API to retrieve its value.

The XugReturn bean should be embedded within a bean used for returning data from the Web service or EJB method, or the data bean should extend the XugReturn class. For the return bean, all other bean properties should be of simple type, or arrays of such. One property can be of type XugReturn, and may have any name desired.

Note that a Web service or EJB method that returns only simple types (or arrays of simple types) cannot choose values for the Tuxedo return value or Tuxedo user return code. In that case and for return beans where XugReturn is not used, the Tuxedo return value will be TPSUCCESS, unless there is a Tuxedo error or XMLink Universal Gateway error. The Tuxedo user return code will be 0, when not specified.

The following example illustrates the use of XugReturn: 

package myclasses.people;
import com.prolifics.xug.XugReturn;
public class PersonA implements java.io.Serializable
{
private String lastName;
private String firstName;
private XugReturn xugRet;

public PersonA(String lastName, String firstName)
{
this.lastName = lastName;
this.firstName = firstName;
}

public PersonA() {}

public void setXugReturn(XugReturn xugRet) {this.xugRet = xugRet;}
public void setLastName(String lastName) {this.lastName = lastName;}
public void setFirstName(String firstName) {this.firstName = firstName;}

public XUGReturn getXugReturn() { return xugRet; }
public String getLastName() { return lastName; }
public String getFirstName() { return firstName; }
}

You can also return a bean which extends XugReturn. Here is an example of that: 

package myclasses.people;
import com.prolifics.xug.XugReturn;
public class PersonB
extends XugReturn
implements java.io.Serializable
{
private String lastName;
private String firstName;

public PersonB(String lastName, String firstName)
{
this.lastName = lastName;
this.firstName = firstName;
}
public PersonB() {}

public void setLastName(String lastName) {this.lastName = lastName;}
public void setFirstName(String firstName) {this.firstName = firstName;}

public String getLastName() { return lastName; }
public String getFirstName() { return firstName; }
}

The following Java code sample for your Web service illustrates a possible way to use PersonA: 

// code fragment
PersonA person = new PersonA("Doe", "John");
int rval = XugReturn.XUGSUCCESS;
int rcode = 2 // appliction specific code
XugReturn xugRet = new XugReturn(rval, rcode);
person.setXugReturn(xugRet);
return person;

The following sample illustrates a possible way to use PersonB: 

// code fragment
PersonB person = new PersonB("Doe", "John");
person.setRcode(2); // application specific code
person.setRval(XugReturn.XUGSUCCESS);
return person;