Hprose 客户端

概述

Hprose 2.0 for Java 支持两种底层网络协议绑定的客户端：HTTP 客户端 和 TCP 客户端。

其中 HTTP 客户端支持跟 HTTP、HTTPS 绑定的 Hprose 服务器通讯。

TCP 客户端支持跟 TCP 绑定的 Hprose 服务器通讯，并且支持全双工和半双工两种模式。

尽管支持这两种不同的底层网络协议，但除了在对涉及到底层网络协议的参数设置上有所不同以外，其它的用法都完全相同。因此，我们在下面介绍 Hprose 客户端的功能时，若未涉及到底层网络协议的区别，就以 HTTP 客户端为例来进行说明。

创建客户端

创建客户端有两种方式，一种是直接使用构造器方法，另一种是使用工厂方法 create。

使用构造器方法创建客户端

HproseClient 是一个抽象类，因此它不能作为构造器直接使用。如果你想创建一个具体的底层网络协议绑定的客户端，你可以将它作为父类，至于如何实现一个具体的底层网络协议绑定的客户端，这已经超出了本手册的内容范围，这里不做具体介绍，有兴趣的读者可以参考 HproseHttpClient、HproseTcpClient 这两个底层网络协议绑定客户端的实现源码。

HproseHttpClient 是 Hprose 的 HTTP 客户端。HproseTcpClient 是 Hprose 的 TCP 客户端。

public HproseHttpClient();
public HproseHttpClient(String uri);
public HproseHttpClient(HproseMode mode);
public HproseHttpClient(String uri, HproseMode mode);
public HproseHttpClient(String[] uris);
public HproseHttpClient(String[] uris, HproseMode mode);

HproseTcpClient 构造器参数跟上面的 HproseHttpClient 参数相同，这里就不在单独列出了。

使用无参构造器创建的客户端，在进行调用前，需要先调用 useService 方法初始化服务器地址。

uri 和 uris 参数是服务器的地址，可以填写一个，也可以填写一组。当填写一组服务器时，客户端会从这些地址当中随机选择一个作为服务地址。因此需要保证这些地址发布的都是完全相同的服务。另外需要注意，当使用 HproseHttpClient 构造器时，地址必须为 http:// 或 https:// 开头的地址。而当使用 HproseTcpClient 构造器时，地址必须为 tcp://, tcp4:// 或 tcp6:// 开头的地址。

mode 参数表示在数据传输时，对于对象序列化采用何种方式，默认是采用 MemberMode 进行序列化，通常不需要修改该设置。

通过工厂方法 create 创建客户端

public static HproseClient create(String uri) throws IOException, URISyntaxException;
public static HproseClient create(String uri, HproseMode mode) throws IOException, URISyntaxException;
public static HproseClient create(String[] uris, HproseMode mode) throws IOException, URISyntaxException;

工厂方法可以直接在 HproseClient 类上调用，它会根据服务器地址来确定创建什么类型的客户端。如果你需要针对具体传输协议进行一些相关设置，可以将返回值类型转换为 HproseHttpClient 或 HproseTcpClient 进行操作。

当指定一组服务器地址时，需要保证它们的底层传输协议是相同的，服务也是完全相同的。

客户端属性

timeout 属性

public final int getTimeout();
public final void setTimeout(int timeout);

该属性默认值为 30000，单位是毫秒（ms）。该设置必须大于 0。

该属性表示当前客户端在调用时的超时时间，如果调用超过该时间后仍然没有返回，则会以超时错误返回。

你也可以针对某个调用进行单独设置。

failswitch 属性

public final boolean isFailswitch();
public final void setFailswitch(boolean failswitch);

该属性默认值为 false。

该属性表示当前客户端在因网络原因调用失败时是否自动切换服务地址。当客户端服务地址仅设置一个时，不管该属性值为何，都不会切换地址。

你也可以针对某个调用进行单独设置。

idempotent 属性

public final boolean isIdempontent();
public final void setIdempontent(boolean idempontent);

该属性默认值为 false。

该属性表示调用是否为幂等性调用，幂等性调用表示不论该调用被重复几次，对服务器的影响都是相同的。幂等性调用在因网络原因调用失败时，会自动重试。如果 failswitch 属性同时被设置为 true，并且客户端设置了多个服务地址，在重试时还会自动切换地址。

你也可以针对某个调用进行单独设置。

retry 属性

public final int getRetry();
public final void setRetry(int retry);

该属性默认值为 10。

该属性表示幂等性调用在因网络原因调用失败后的重试次数。只有 idempotent 属性为 true 时，该属性才有作用。

你也可以针对某个调用进行单独设置。

byref 属性

public final boolean isByref();
public final void setByref(boolean byref);

该属性默认值为 false。

该属性表示调用是否为引用参数传递。当设置为引用参数传递时，服务器端会传回修改后的参数值（即使没有修改也会传回）。因此，当不需要该功能时，设置为 false 会比较节省流量。

你也可以针对某个调用进行单独设置。

simple 属性

public final boolean isSimple();
public final void setSimple(boolean simple);

该属性默认值为 false。

该属性表示调用中所传输的数据是否为简单数据。简单数据是指：null、数字（包括整数、长整数、浮点数）、boolean 值、字符串、二进制数据、日期时间等基本类型的数据或者不包含引用的数组、Map 和对象。当该属性设置为 true 时，在进行序列化操作时，将忽略引用处理，加快序列化速度。但如果数据不是简单类型的情况下，将该属性设置为 true，可能会因为死循环导致堆栈溢出的错误。

另外，对于不包含引用 Map 和对象，设置 simple 为 true 可能不会加快速度，反而会减慢。因为默认情况下，hprose 会对 Map 中的重复字符串的键值进行引用处理，这种引用处理可以对序列化起到优化作用。而关闭引用处理，也就关闭了这种优化。

你也可以针对某个调用进行单独设置。

因为不同调用的数据可能差别很大，因此，建议不要修改默认设置，而是针对某个调用进行单独设置。