Sample Java ORB Protocol Sepcification

 

1       协议概述

1.1    关于sjop

sjop全称是Sample Java ORB Protocol（简单Java对象请求代理协议）。相类似的协议有DCOM，CORBA，SOAP等等，相比之下sjop是一种极其简单并且高效的对象请求代理协议。

 

1.2    sjop应用

sjop协议在minij2ee应用服务器中被实现，用于在php或其他非Java客户中调用minij2ee应用服务器中的EJB组件。

 

2       协议内容

2.1    概述

sjop是基于文本的协议，这也正是他简单的原因。sjop通讯使用面向流的通讯协议，比如TCP/IP，通讯模式采用请求/应答模式。

 

2.2    数据类型

sjop定义了以下基本数据类型：

java.lang.String：字符串

java.lang.Short：短整型

java.lang.Integer：整型

java.lang.Long：长整型

java.lang.Boolean：布尔值，“true”或者“false”

java.lang.Float：浮点数

java.lang.Double：双精度浮点数

 

sjop定义以下特殊的数据类型：

void：当调用的方法无返回值时，使用void。

phpext.objref：Java对象的引用句柄，用于返回创建的Java对象，调用Java对象的方法调用或将Java对象作为参数。

 

2.3    请求

sjop的请求格式为：

request:function

request body

EOR

其中function是请求的功能，request body根据请求的功能不同而不同。EOR是请求体结束的标志。

 

2.3.1   参数列表

request body一般会包含一个参数列表parameter list，用于指定调用构造函数或方法的参数。parameter list由若干行参数条目组成，每个参数条目的格式如下：

param:type:value

例如：

param:java.lang.String:abcd

param:java.lang.Integer:1234

由于每一个参数条目是一行，所以对于java.lang.String类型的参数，如果value里包含’/n’，则要进行编码。

 

2.3.2   创建对象

创建对象请求的格式为：

request:new

classname:name of java class

parameter list

EOR

请求成功将在应答里返回一个phpext.objref类型的值，是创建的Java对象的引用句柄。

 

2.3.3   删除对象

删除对象请求的格式为：

request:delete

objref:object reference

EOR

请求成功，将在删除object reference指定的被代理的Java对象。object reference是创建对象请求返回的Java对象的引用句柄，或者是方法调用或静态方法调用返回的phpext.objref类型值。

 

在minij2ee应用服务器的实现中，在一定时间内没有被引用的对象将被自动删除。

 

2.3.4   方法调用

方法调用请求的格式为：

request:call

objref: object reference

methodname:name of method

parameter list

EOR

请求返回方法调用的结果或异常。object reference是创建对象请求返回的Java对象的引用句柄，或者是方法调用或静态方法调用返回的phpext.objref类型值。

 

2.3.5   静态方法调用

静态方法调用的请求格式为：

request:call

classname:name of java class

methodname:name of method

parameter list

EOR

静态方法调用类似方法调用，只是将Java对象引用句柄改为了Java类名称，因为调用静态方法是不需要Java对象实例的。

 

2.4    应答

应答分成功和异常两种。

成功应答格式为：

responce:ok

result:type:value

type是返回值的类型，value是返回值。若请求没有返回值，则type为void，value为null。

异常应答格式为：

responce: error

exception:type:value

type是异常的类名称，如java.io.IOException，value是异常的描述。

 

3       sjop API

minij2ee应用服务器软件包中提供了minij2ee sjop实现的API，在php/sjop目录下，可以用于在C/C++程序中方问minij2ee应用服务器上的EJB组件。

 

sjop API提供了以下函数（宏）：

u       sjop_get_connection

函数原型：

HCOMM_CONNECTION sjop_get_connection(char* ip,char* port);

描述：

sjop_get_connection获取一条同minij2ee sjop服务器的连接，用于进行请求。ip是服务器的ip地址，port是服务器的端口号。一条连接可以用于多次请求。

u       sjop_free_connection

函数原型：

void sjop_free_connection(HCOMM_CONNECTION hconn);

描述：

sjop_free_connection释放一条同minij2ee sjop服务器的连接。

 

u       sjop_minij2ee_new_javaobj

函数原型：

PHPEXTRESPONCE* sjop_minij2ee_new_javaobj(HCOMM_CONNECTION conn,char* classname,...);

描述：

sjop_minij2ee_new_javaobj函数发送创建对象的请求。conn是同minij2ee sjop服务器的连接。函数返回一个PHPEXTRESPONCE结构指针包含了应答的内容。

例子：

PHPEXTRESPONCE* r= sjop_minij2ee_new_javaobj(hconn, “java.io.FileInputStream”, “java.lang.String”, “c:/somefile” );

 

u       sjop_minij2ee_delete_javaobj

函数原型：

PHPEXTRESPONCE* sjop_minij2ee_delete_javaobj(HCOMM_CONNECTION conn,HJAVAOBJ jobj);

描述：

sjop_minij2ee_delete_javaobj 函数发送删除对象的请求。conn是同minij2ee sjop服务器的连接。函数返回一个PHPEXTRESPONCE结构指针包含了应答的内容。

 

u       sjop_minij2ee_call_javaobj

函数原型：

PHPEXTRESPONCE* sjop_minij2ee_call_javaobj(HCOMM_CONNECTION conn,HJAVAOBJ jobj,char* methodname,...);

描述：

sjop_minij2ee_call_javaobj 函数发送方法调用的请求。conn是同minij2ee sjop服务器的连接。函数返回一个PHPEXTRESPONCE结构指针包含了应答的内容。

例子：

PHPEXTRESPONCE* r=sjop_minij2ee_call_javaobj(hconn, objref, “skip” , “java.lang.Long”, 16);

 

u       sjop_minij2ee_callstatic_javaobj

函数原型：

PHPEXTRESPONCE* sjop_minij2ee_callstatic_javaobj(HCOMM_CONNECTION conn,char* classname,char* methodname,...);

描述：

sjop_minij2ee_callstatic_javaobj 函数发送静态方法调用的请求。conn是同minij2ee sjop服务器的连接。函数返回一个PHPEXTRESPONCE结构指针包含了应答的内容。

例子：

PHPEXTRESPONCE* r= sjop_minij2ee_callstatic_javaobj(hconn, “java.lang.System”, “getProperty”, “java.lang.String”, “java.version”);

 

u       sjop_free_response

函数原型：

void sjop_free_responce(PHPEXTRESPONCE* resp);

描述：

sjop_free_response释放发送请求返回的PHPEXTRESPONCE结构指针。

 

PHPEXTRESPONCE结构定义如下：

typedef struct

{

int succ;  //请求是否成功

char* exptype;  //若异常，exptype指示了异常类的名称

char* expvalue;  //若异常，expvalue指示了异常的描述

char* resulttype;  //返回值类型，见数据类型

union

{

       int    int_value;

       char*  string_value;

       double double_value;

       int    objref_value;

}result;  //返回值的联合，根据返回值类型不同而使用不同的成员，加下表：

返回值类型	对应的result中的成员
java.lang.Short java.lang.Integer java.lang.Long java.lang.Boolean	int_value
java.lang.String	string_value
java.lang.Float java.lang.Double	double_value
phpext.objref	objref_value
void	无

}PHPEXTRESPONCE;

 

以下的宏可以用来访问PHPEXTRESPONCE结构指针：

#define sjop_resp_ok(resp)             ((resp)->succ)

#define sjop_resp_error(resp)           (!(resp)->succ)

#define sjop_resp_exp_type(resp)        ((resp)->exptype)

#define sjop_resp_exp_value(resp)       ((resp)->expvalue)

#define sjop_resp_result_type(resp)      ((resp)->resulttype)

#define sjop_resp_result_int(resp)        ((resp)->result.int_value)

#define sjop_resp_result_string(resp)     ((resp)->result.string_value)

#define sjop_resp_result_double(resp)    ((resp)->result.double_value)

#define sjop_resp_result_javaobj(resp)    ((resp)->result.objref_value)

 http://www.minij2ee.com/