Hprose for php(三)——客户端

本文参考了Hprose官方的用户手册，Hprose官网：http://www.hprose.com/ 

如果你还未自己动手做过Hprose的实践，请先看《Hprose for php(一)——快速入门》

本文将介绍Hprose for php客户端的更多细节。

1、直接通过远程方法名进行远程调用

在快速入门一章中，我们已经见识过这种方式的调用了，这里再来具一个例子来进行说明：

<?php
include("hprose/hproseHttpClient.php");
$client = new HproseHttpClient("http://www.hprose.com/example/");
echo "<pre>";
echo $client->sum(1, 2, 3, 4, 5);
echo "\r\n";
echo $client->Sum(6.0, 7.0, 8.0);
echo "\r\n";
$userList = $client->getUserList();
print_r($userList);
echo "</pre>";
?>

从这个例子中，我们可以看出通过远程方法名进行调用时，远程方法名是不区分大小写的，所以不论是写sum还是Sum都可以正确调用，如果远程方法返回结果中包含有某个类的对象，而该类并没有在客户端明确定义的话，Hprose会自动帮你生成这个类的定义（例如上例中的User类），并返回这个类的对象。

2、通过Invoke方法进行远程调用

非引用参数传递

<?php
include("hprose/hproseHttpClient.php");
$client = new HproseHttpClient("http://www.hprose.com/example/");
echo "<pre>";
$args = array(1, 2, 3, 4, 5);
echo $client->invoke("sum", $args);
echo "\r\n";
$args = array(6.0, 7.0, 8.0);
echo $client->invoke("Sum", $args);
echo "\r\n";
$userList = $client->invoke("getUserList");
print_r($userList);
echo "</pre>";
?>

运行结果与上面例子的运行结果完全相同。但是我们发现用invoke方法并不方便，因为当有参数时，必须要把参数单独放入一个变量中才可以进行传递。所以通常我们无需直接使用invoke方法，除非我们需要动态调用。另外，还有一种情况下，你会用到invoke方法，那就是在进行引用参数传递时。

引用参数传递

下面这个例子很好的说明了如何进行引用参数传递：

<?php
include("hprose/hproseHttpClient.php");
$client = newHproseHttpClient("http://www.hprose.com/example/");
echo"<pre>";
$args =array(array("Mon"=>1,"Tue"=>2,"Wed"=>3,"Thu"=>4,"Fri"=>5,"Sat"=>6,"Sun"=>7));
echo"args(before invoke):\r\n";
print_r($args);
$result =$client->invoke("swapKeyAndValue", $args, true);
echo"args(after invoke):\r\n";
print_r($args);
echo"result:\r\n";
print_r($result);
echo"</pre>";
?>

我们看到运行前后，$args中的值已经改变了。

这里有一点要注意，当参数本身是数组时，该数组应该作为参数数组的第一个元素传递，否则程序将会出错，或者在调用中陷入等待状态，这样的错误不容易被找到，因此一定要注意这一点。

3、异常处理

Hprose for PHP的客户端只支持同步调用，因此在调用过程中，如果服务器端发生错误，异常将在客户端被直接抛出，使用try...catch语句块即可捕获异常，通常服务器端调用返回的异常是HproseException类型。但是在调用过程中也可能抛出其它类型的异常。

例如，当调用不存在的方法时：

<?php
include("hprose/hproseHttpClient.php");
$client = new HproseHttpClient("http://www.hprose.com/example/");
echo "<pre>";
try {
  echo $client->unexistMethod();
}
catch (Exception $e) {
  print_r($e);
}
echo "</pre>";
?>

4、超时设置

Hprose 1.2 for PHP及其之后的版本中增加了超时设置。只需要设置客户端对象上的setTimeout属性即可，单位为毫秒。当调用超过timeout的时间后，调用将被中止。

5、HTTP参数设置

目前的版本只提供了http客户端实现，针对于http客户端，有一些特别的设置，例如代理服务器、http标头等设置，下面我们来分别介绍。

代理服务器

默认情况下，代理服务器是被禁用的。可以通过setProxy来设置http代理服务器的地址和端口。参数是字符串，例如："tcp://10.54.1.39:8000"，默认值为NULL。

HTTP标头

有时候您可能需要设置特殊的http标头，例如当您的服务器需要Basic认证的时候，您就需要提供一个Authorization标头。设置标头很简单，只需要调用setHeader方法就可以啦，该方法的第一个参数为标头名，第二个参数为标头值，这两个参数都是字符串型。如果将第二个参数设置为NULL，则表示删除这个标头。

标头名不可以为以下值：Context-Type、Context-Length、Host。

因为这些标头有特别意义，客户端会自动设定这些值。

另外，Cookie这个标头不要轻易去设置它，因为设置它会影响Cookie的自动处理，如果您的通讯中用到了Session，通过setHeader方法来设置Cookie标头，将会影响Session的正常工作。

6、保持会话

当浏览器访问一个PHP页面，而这个PHP页面又通过Hprose客户端去访问另一台Hprose服务器时，通常是不能保持浏览器到Hprose客户端访问的那台Hprose服务器会话的。那有什么办法能够将这个会话保持并传递到浏览器吗？

Hprose 1.2 for PHP中提供了这样的功能，只需要在使用客户端页面的开头如下调用就可以了。

session_start();
include("hproseHttpClient.php");
HproseHttpClient::keepSession();

7、调用结果返回模式

有时候调用的结果需要缓存到文件或者数据库中，或者需要查看返回结果的原始内容。这时，单纯的普通结果返回模式就有些力不从心了。Hprose 1.3提供更多的结果返回模式，默认的返回模式是Normal，开发者可以根据自己的需要将结果返回模式设置为Serialized，Raw或者RawWithEndTag。

Serialized模式

Serialized模式下，结果以序列化模式返回，在PHP中，序列化的结果以String类型返回。用户可以通过HproseFormatter.unserialize方法来将该结果反序列化为普通模式的结果。因为该模式并不对结果直接反序列化，因此返回速度比普通模式更快。

在调用时，通过在回调方法参数之后，增加一个结果返回模式参数来设置结果的返回模式，结果返回模式是一个枚举值，它的有效值在HproseResultMode枚举中定义。

Raw模式

Raw模式下，返回结果的全部信息都以序列化模式返回，包括引用参数传递返回的参数列表，或者服务器端返回的出错信息。该模式比Serialized模式更快。

RawWithEndTag模式

完整的Hprose调用结果的原始内容中包含一个结束符，Raw模式下返回的结果不包含该结束符，而RawWithEndTag模式下，则包含该结束符。该模式是速度最快的。

这三种模式主要用于实现存储转发式的Hprose代理服务器时使用，可以有效提高Hprose代理服务器的运行效率。