咖啡舞者

Java RMI 之 Introduction

咖啡舞者 — Fri, 04 Jul 2008 15:19:21 +0800

作者: 咖啡舞者链接：http://07360591.javaeye.com/blog/211576 发表时间: 2008年07月04日

声明：本文系JavaEye网站发布的原创博客文章，未经作者书面许可，严禁任何网站转载本文，否则必将追究法律责任！

Java RMI 之 Introduction

注：主要内容参考官方文档。同时已经有人把翻译过Sun上RMI的lesson，如果想学习技术实例，可以查看，参考资源给出了链接。

Overview

Java Remote Method Invocation (Java RMI) enables the programmer to create distributed Java technology-based
to Java technology-based applications, in which the methods of remote Java objects can be invoked from
other Java virtual machines, possibly on different hosts. RMI uses object serialization to marshal and
unmarshal parameters and does not truncate types, supporting true object-oriented polymorphism.

使用Java RMI，可以创建分布式的Java应用程序，远程的Java对象的方法可以被不同的主机中不同的Java虚拟机调用。RMI使用对象序列化传递参数，并且不会丢失类型，支持面向对象的多态性。

Introduction

1.1 Background(背景)

Distributed systems require that computations running in different address spaces, potentially on different
hosts, be able to communicate. For a basic communication mechanism, the JavaTM programming language
supports sockets, which are flexible and sufficient for general communication. However, sockets require the
client and server to engage in applications-level protocols to encode and decode messages for exchange, and the design of such protocols is cumbersome and can be error-prone.

An alternative to sockets is Remote Procedure Call (RPC), which abstracts the communication interface to the
level of a procedure call. Instead of working directly with sockets, the programmer has the illusion of
calling a local procedure, when in fact the arguments of the call are packaged up and shipped off to the
remote target of the call. RPC systems encode arguments and return values using an external data
representation, such as XDR.

RPC, however, does not translate well into distributed object systems, where communication between
program-level objects residing in different address spaces is needed. In order to match the semantics of
object invocation, distributed object systems require remote method invocation or RMI. In such systems, a
local surrogate (stub) object manages the invocation on a remote object.

The Java platform's remote method invocation system described in this specification has been specifically
designed to operate in the Java application environment. The Java programming language's RMI system assumes the homogeneous environment of the Java virtual machine (JVM), and the system can therefore take advantage
of the Java platform's object model whenever possible.

分布式系统要求计算能不同的地址空间上，也就是说在不同的主机上，要能进行通讯，对于基本的Java通讯机制，Java支持Sokets，对于一般的通讯来说Sockets足够了，但是Sockets要求客户端和服务器端使用应用级别的协议交换消息，并且这个协议比较笨重。

另外一个选择就是RCP，RCP就是针对远程调用级别抽象出一个通讯接口。而不是直接的使用sockets，参数的调用被包装起来，使用时看起来就像本地调用过程，RCP系统编码参数和返回值使用的是外部数据请求，比如XDR

在分布式系统中，程序级别的对象必须存在不同的地址空间中，然而RCP不能很好的支持。为了匹配语法上的对象调用，分布式系统要求使用RMI，在这样一个系统中，一个代理（存根）对象管理一个远程对象的调用。

规范中描述Java平台RMI系统被是为Java应用环境特别设计。Java RMI系统假定其拥有相似的JVM环境

1.2 System Goals(系统目标)

The goals for supporting distributed objects in the Java programming language are:

    * Support seamless remote invocation on objects in different virtual machines
    * Support callbacks from servers to applets
    * Integrate the distributed object model into the Java programming language in a natural way while
      retaining most of the Java programming language's object semantics
    * Make differences between the distributed object model and local Java platform's object model apparent
    * Make writing reliable distributed applications as simple as possible
    * Preserve the type-safety provided by the Java platform's runtime environment
    * Support various reference semantics for remote objects; for example live (nonpersistent) references,
persistent references, and lazy activation
    * Maintain the safe environment of the Java platform provided by security managers and class loaders

在Java中支持分布式对象的目标如下：

    * 支持不同的虚拟机之间无缝的调用远程对象。
    * 支持从服务器端回执给applets
    * 保持大部分java对象原有的语义，以一种很自然的方式把分布式对象模型整合于Java语言
    * 区分分布式对象模型和本地平台的对象模型
    * 尽可能简单的构建可靠的分布式应用
    * 有Java运行环境保护类型（Type）安全
    * 远程对象支持各种语义上的引用（reference），比如：live references,持久引用和延迟激活。
      使用安全管理器（security managers）和类加载器（class loaders）保护java平台的环境安全。

Java Distributed Object Model

2.1 Distributed Object Applications

RMI applications are often comprised of two separate programs: a server and a client. A typical server
application creates a number of remote objects, makes references to those remote objects accessible, and
waits for clients to invoke methods on those remote objects. A typical client application gets a remote
reference to one or more remote objects in the server and then invokes methods on them. RMI provides the
mechanism by which the server and the client communicate and pass information back and forth. Such an
application is sometimes referred to as a distributed object application.

Distributed object applications need to:
    * Locate remote objects
Applications can use one of two mechanisms to obtain references to remote objects. An application can
register its remote objects with RMI's simple naming facility, the rmiregistry, or the application can pass
and return remote object references as part of its normal operation.
    * Communicate with remote objects
Details of communication between remote objects are handled by RMI; to the programmer, remote communication
looks like a standard method invocation.
    * Load class bytecodes for objects that are passed as parameters or return values
Because RMI allows a caller to pass objects to remote objects, RMI provides the necessary mechanisms for
loading an object's code as well as transmitting its data.

RMI应用程序经常是由两个单独的程序组成：服务器端和客户端，
一个典型的服务器端应用创建一系列远程对象，并使其对象的引用可访问，等客户端来调用远程对象的方法。一个典型的客户端获取一个服务器端远程对象（一个或多个）的远程引用，然后调用他们的方法。RMI提供机制让服务器端和客户端进行通讯和来回传递信息。像这样一个应用就是分布式应用。

分布式应用必须：

   * 查找远程对象
    应用程序下面两者之一的机制来获得远程对象的引用。一个应用程序可以使用RMI的简单命名在注册处注册它的远程对象，或者应用程序可以像普通操作一样传递和返回远程对象的引用。

   *与远程对象进行通讯、
    远程对象之间的通讯具体操作有RMI来提供，使用时只要当作正常的方法调用即可。

   * 加载对象的字节码使其可以作为参数或返回值传递。
     因为RMI允许调用者传递对象到远程对象，RMI提供必要的机制加载对象的代码和传输它数据。

The illustration below depicts an RMI distributed application that uses the registry to obtain references to
a remote object. The server calls the registry to associate a name with a remote object. The client looks
up the remote object by its name in the server's registry and then invokes a method on it. The illustration also shows that the RMI system uses an existing web server to load bytecodes of classes written in the Java programming language, from server to client and from client to server, for objects when needed. RMI can load
class bytecodes using any URL protocol (e.g., HTTP, FTP, file, etc.) that is supported by the Java platform.

下面这幅图描述了一个RMI分布式应用程序，用户使用registry获得一个远程对象的引用，Server端调用registry使用名字和一个远程对象关联。客户端在Server的registry中查找远程对象的引用并调用其方法。同时这个图也描述了，在需要时，RMI系统使用已经存在的 web server在client端和Server端之间加载Java Class的字节码。RMI可以使用URL协议（如e.g., HTTP, FTP, file, etc），这些Java平台都支持

2.3 The Distributed and Nondistributed Models Contrasted

The Java SE platform's distributed object model differs from the Java SE platform's object model in these
ways:
*    Clients of remote objects interact with remote interfaces, never with the implementation classes of
those interfaces.
*    Non-remote arguments to, and results from, a remote method invocation are passed by copy rather than by
reference. This is because references to objects are only useful within a single virtual machine.
*    A remote object is passed by reference, not by copying the actual remote implementation.
*    The semantics of some of the methods defined by class java.lang.Object are specialized for remote
objects.
*    Since the failure modes of invoking remote objects are inherently more complicated than the failure
modes of invoking local objects, clients must deal with additional exceptions that can occur during a remote
method invocation.

Java SE平台的分布式对象模型普通对象模型的区别：

* 远程对象的Client端只与远程接口进行交互，不触及接口的实现。
* 不管是参数传递还是值返回，远程方法调用时传递的都是值的Copy而不是引用，因为一个对象的引用只有在单个虚拟机中有用。
* 远程对象传递的是引用，而不是copy实际的远程实现。
* Java.lang.Object为远程对象定义了一些专门的方法
* 调用远程对象天生就比调用本地方法，在失败mode上要复杂。所以客户端要处理远程调用中出现的额外的异常

参考资源：
RMI lesson翻译: http://www.blogjava.net/jht/archive/2007/05/09/116216.html
官方文档：http://java.sun.com/javase/6/docs/technotes/guides/rmi/index.html

本文的讨论也很精彩，浏览讨论>>

JavaEye推荐

Java远程方法调用

咖啡舞者 — Fri, 04 Jul 2008 15:00:22 +0800

作者: 咖啡舞者链接：http://07360591.javaeye.com/blog/211561 发表时间: 2008年07月04日

声明：本文系JavaEye网站发布的原创博客文章，未经作者书面许可，严禁任何网站转载本文，否则必将追究法律责任！

来源: 网络

概述

　　Java Remote Method Invocation ( RMI -- Java远程方法调用)允许您使用Java编写分布式对象。本文将介绍RMI的优点以及如何将其连接到现有的和原有的系统中，以及与用Java 编写的组件的连接。

　　RMI为采用Java对象的分布式计算提供了简单而直接的途径。这些对象可以是新的Java对象，也可以是围绕现有API的简单的Java包装程序。Java体现了“编写一次就能在任何地方运行的模式。而RMI可将Java模式进行扩展，使之可在任何地方运行”。

　　因为RMI是以Java为核心的，所以，它将Java的安全性和可移植性等强大功能带给了分布式计算。您可将代理和梢务逻辑等属性移动到网络中最合适的地方。如果您要扩展Java在系统中的使用，RMI将使您充分利用其强大功能。

　　RMI可利用标准Java本机方法接口JNI与现有的和原有的系统相连接。RMI还可利用标准JDBC包与现有的关系数据库连接。RMI/JNI和RMI/JDBC相结合，可帮助您利用RMI与目前使用非Java语言的现有服务器进行通信，而且在您需要时可扩展Java在这些服务器上的使用。RMI可帮助您在扩展使用时充分利用Java的强大功能。

优点

　　从最基本的角度看，RMI是Java的远程过程调用(RPC)机制。与传统的RPC系统相比，RMI具有若干优点，因为它是Java面向对象方法的一部分。传统的RPC系统采用中性语言，所以是最普通的系统--它们不能提供所有可能的目标平台所具有的功能。

　　RMI以Java为核心，可与采用本机方法与现有系统相连接。这就是说，RMI可采用自然、直接和功能全面的方式为您提供分布式计算技术，而这种技术可帮助您以不断递增和无缝的方式为整个系统添加Java功能。

RMI的主要优点如下：

　面向对象：RMI可将完整的对象作为参数和返回值进行传递，而不仅仅是预定义的数据类型。也就是说，您可以将类似Java哈希表这样的复杂类型作为一个参数进行传递。而在目前的RPC系统中，您只能依靠客户机将此类对象分解成基本数据类型，然后传递这些数据类型，最后在服务器端重新创建哈希表。RMI则不需额外的客户程序代码(将对象分解成基本数据类型)，直接跨网传递对象。
　可移动属性：RMI可将属性(类实现程序)从客户机移动到服务器，或者从服务器移到客户机。例如，您可以定义一个检查雇员开支报告的接口，以便察看雇员是否遵守了公司目前实行的政策。在开支报告创建后，客户机就会从服务器端获得实现该接口的对象。如果政策发生变化，服务器端就会开始返回使用了新政策的该接口的另一个实现程序。您不必在用户系统上安装任何新的软件就能在客户端检查限制条件--从而向用户提供烁快的反馈，并降低服务器的工作量。这样就能具备最大的灵活性，因为政策改变时只需要您编写一个新的Java类，并将其在服务器主机上安装一次即可。
　设计方式：对象传递功能使您可以在分布式计算中充分利用面向对象技术的强大功能，如二层和三层结构系统。如果您能够传递属性，那么您就可以在您的解决方案中使用面向对象的设计方式。所有面向对象的设计方式无不依靠不同的属性来发挥功能，如果不能传递完整的对象--包括实现和类型--就会失去设计方式上所提供的优点。
　安　　全：RMI使用Java内置的安全机制保证下载执行程序时用户系统的安全。RMI使用专门为保护系统免遭恶意小应用程序侵害而设计的安全管理程序，可保护您的系统和网络免遭潜在的恶意下载程序的破坏。在情况严重时，服务器可拒绝下载任何执行程序。
便于编写和使用：RMI使得Java远程服务程序和访问这些服务程序的Java客户程序的编写工作变得轻松、简单。远程接口实际上就是Java接口。服务程序大约用三行指令宣布本身是服务程序，其它方面则与任何其它Java对象类似。这种简单方法便于快速编写完整的分布式对象系统的服务程序，并快速地制做软件的原型和早期版本，以便于进行测试和评估。因为RMI程序编写简单，所以维护也简单。
　可连接现有/原有的系统：RMI可通过Java的本机方法接口JNI与现有系统进行进行交互。利用RMI和JNI，您就能用Java语言编写客户端程序，还能使用现有的服务器端程序。在使用RMI/JNI与现有服务器连接时，您可以有选择地用Java重新编写服务程序的任何部分，并使新的程序充分发挥Java的功能。类似地，RMI可利用JDBC、在不修改使用数据库的现有非Java源代码的前提下与现有关系数据库进行交互。
　编写一次，到处运行：RMI是Java“编写一次，到处运行 ”方法的一部分。任何基于RMI的系统均可100%地移植到任何Java虚拟机上，RMI/JDBC系统也不例外。如果使用RMI/JNI与现有系统进行交互工作,则采用JNI编写的代码可与任何Java虚拟机进行编译、运行。
　分布式垃圾收集：RMI采用其分布式垃圾收集功能收集不再被网络中任何客户程序所引用的远程服务对象。与Java 虚拟机内部的垃圾收集类似，分布式垃圾收集功能允许用户根据自己的需要定义服务器对象，并且明确这些对象在不再被客户机引用时会被删除。
　并行计算：RMI采用多线程处理方法，可使您的服务器利用这些Java线程更好地并行处理客户端的请求。Java分布式计算解决方案：RMI从JDK 1.1开始就是Java平台的核心部分，因此，它存在于任何一台1.1 Java虚拟机中。所有RMI系统均采用相同的公开协议，所以，所有Java 系统均可直接相互对话，而不必事先对协议进行转换。

传递属性

　　前面我们讲到，RMI可以传递属性，并简单介绍了一下一个有关开支报告程序的情况。下面我们将深入讨论如何设计这样的系统。这样介绍的目的是使您能够利用RMI的功能将属性从一个系统传递到另一个系统，并随心所欲地安排当前的计算地点，并便于将来的改变。下面的例子并未涉及真实世界可能发生的所有问题，但可帮助读者了解处理问题的方法。

服务器定义的策略

　　图1是可进行动态配置的开支报告系统的示意图。客户机向用户显示图形用户界面(GUI)，用户填写开支报告。客户机程序使用RMI与服务器进行通信。服务器使用JDBC( Java关系数据库连接包)将开支报告存储在数据库中。至此，这看起来与其它多层次系统大同小异，但有一个重大区别-- RMI能下载属性。
假定公司关于开支报告的政策发生改变。例如，目前公司只要求对超过20美元的开支需开具发票。但到明天，公司认为这太宽松了，便决定除不超过20美元的餐费以外，任何开支均需开具发票。如果不能下载属性的话，那么在设计便于修改的系统时您可选择下列方法之一：

　　用客户端安装与政策有关的程序。政策改变时，必须更新包含此政策的所有客户端程序。您可在若干服务器上安装客户程序，并要求所有用户从这些服务器之一运行客户程序，从而减少问题。但这仍不能彻底解决问题-- 那些让程序运行好几天的用户就无法使程序更新，而总是会有一些用户为了方便而把软件复制到本地磁盘上。
　　您可要求服务器在每次向开支报告添加项目时检查政策。但这样就会在客户机和服务器之间产生大量数据流，并增加服务器的工作量。这还会使系统变得更加脆弱--网络故障会立即妨碍用户，而不仅仅是只在其呈交开支报告或启动新的报告时对其产生影响。同时，添加项目的速度也会变慢，因为这需要穿越整个网络往返一圈才能到达(不堪重负的)服务器。
您可在呈交报告时要求服务器对政策进行检查。这样就会使用户创建很多必须待批报告的错误项目，而不是立刻捕捉到第一个错误，从而使用户有机会停止制造错误。为避免浪费时间，用户需要立刻得到有关错误的反馈。
　　有了RMI，您就能以简单的方法调用程序从服务器得到属性，从而提供了一种灵活的方式，将计算任务从服务器卸载到客户机上，同时为用户提供速度更快的反馈。当用户准备编写一份新的开支报告时，客户机就会向服务器要求一个对象，该对象嵌入了适用于该开支报告的当前政策，就如同通过用Java编写的政策接口所表示的那样。该对象可以以任何方式实现当前政策。如果这是客户机RMI首次看到这种专门执行的政策，就会要求服务器提供一份执行过程的副本。如果执行过程将来发生变化，则一种新的政策对象将被返回给客户机，而RMI运行时则会要求得到新的执行过程。
　　这表明，政策永远是动态的。您要想修改政策，就只需简单地编写通用政策接口的新的执行程序，把它安装在服务器上，并对服务器进行配置以返回这种新类型的对象即可。这样，每台客户机都会根据新的政策对新的开支报告进行检查。

这是一种比任何静态方法都更好的方法，原因如下：

　　所有客户机不必暂停或用新的软件来升级--软件可根据需要在不工作时加以更新。
　　服务器不必参与项目检查工作，该工作可在本地完成。
　　允许动态限制，因为对象执行程序(而不仅仅是数据)是在客户机和服务器之间进行传递的。
　　使用户能立刻看到错误。

使客户机在服务器上所能调用的方法的远程接口定义如下：
import java.rmi.*;
public interface ExpenseServer extends Remote {
Policy getPolicy() throws RemoteException;
void submitReport(ExpenseReport report)
throws RemoteException, InvalidReportException;
}
import语句输入Java RMI包。所有RMI类型均在包java.rmi或其子包内定义。接口ExpenseServer是一般的Java接口，具有如下两种有趣的特点：

它扩展了名为Remote的RMI接口，这使该接口标记为可用于远程调用。

它的所有方法均抛出RemoteException，后者用来表示网络或信息故障。

　　远程方法还可抛出您所需要的任何其他例外，但至少必须抛出RemoteException，这样您才能处理只会在分布式系统中发生的错误状态。该接口本身支持两个方法：getPolicy (返回一个实现政策接口的对象)，和submitReport (提交一个完成的开支请求，并在报告无论因何种原因使表格出现错误时，抛出一个例外)。
政策接口本身可声明一种使客户机知道能否在开支报告中添加一个项目的方法：
public interface Policy {
void checkValid (Expenseentry entry)
throws PolicyViolationException;
}
如果该项目有效--即符合当前政策，则该方法可正常返回。否则就会抛出一个描述该错误的例外。政策接口是本地的(而非远程的)，所以将通过本机对象在客户机上执行--在客户机的虚拟机上，而非整个网络上运行的对象。客户机可能运行下列程序：
Policy curPolicy = server.getPolicy();
start a new expense report
show the GUI to the user
while (user keeps adding entries) {
try {
curPolicy.checkValid(entry); // throws exception if not OK
add the entry to the expense report
} catch (PolicyViolationException e) {
show the error to the user
}
}
server.submitReport(report);

　　当用户请求客户机软件启动一份新的开支报告时，客户机就调用server.getPolicy，并要求服务器返回一个包含当前开支政策的对象。添加的每个项目首先都被提交给该政策对象，以获得批准。如果政策对象报告无错误，则该项目就被添加到报告中；否则错误就被显示给用户，而后者可采取修正措施。当用户完成向报告中添加项目时，整个报告就被呈交。服务程序如下：
import java.rmi. *;
import java.rmi.server. *;
class ExpenseServerImpl
extends UnicastRemoteObject
implements ExpenseServer
{
ExpenseServerImpl() throws RemoteException {
// . . . set up server state . . .
}
public Policy getPolicy() {
return new TodaysPolicy();
}
public void submitReport(ExpenseReport report) {
// . . . write the report into the db . . .
}
}
除基本程序包外，我们还输入RMI的服务程序包。类型UnicastRemoteObject 定义了此服务程序远程对象的类型，在本例中，应为单一服务程序而非复制服务(下面还会详细介绍)。Java类ExpenseSeverImpl实现远程接ExpenseServer的方法。远程主机的客户机可使用RMI将信息发送给ExpenseServerImpl对象。

本文中讨论的重要方法是getPolicy，它简单地返回定义当前政策的对象。下面看一个执行政策的例子：

public class TodaysPolicy implements Policy {
public void checkValid(ExpenseEntry entry)
throws PolicyViolationException
{
if (entry.dollars() < 20) {
return; // no receipt required
else if (entry.haveReceipt() == false) {
throw new PolicyViolationException;
}
}
}
TodaysPolicy进行检查的目的是确保无收据的任何项目均少于20美元。如果将来政策发生变化，仅少于20美元的餐费可不受“需要收据”政策的限制，则您可提供新的政策实现：
public class TomorrowsPolicy implements Policy {
public void checkValid(ExpenseEntry entry)
throws PolicyViolationException
{
if (entry.isMeal() && entry.dollars() < 20) {
return; // no receipt required
} else if (entry.haveReceipt() == false) {
throw new PolicyViolationException;
}
}
}
　　编写这个类，并把它安装在服务器上，然后告诉服务器开始提供TomorrowsPolicy对象，而非daysPolicy对象，这样您的整个系统就会开始使用新的政策。当客户机调用服务器的getPolicy方法时，客户机的RMI就会检查返回的对象是否为已知类型。每台客户机首次遇到TomorrowsPolicy时，RMI就会在getPolicy返回前下载政策的实现。客户机可轻松地开始增强这个新的政策。

　　RMI使用标准Java对象序列化机制传递对象。引用远程对象参数作为远程引用传递。如果向某方法提供的参数为原始类型或本机(非远程)对象，则向服务器传递一个深副本。返回值也拾照同样的方式处理，只不过是沿其它方向。RMI可使用户向本机对象传递和返回完整对象图并为远程对象传递和返回引用。

　　在真实的系统中，getPolicy方法可能会有一个可以识别用户及开支报告类型(差旅、客户关系等)的参数，这样可使政策加以区别。您或者可以不要求单独的政策和开支报告对象，但您可以有一种newExpenseReport方法，它可返回一个直接检查政策的ExpenseReport对象。这最后一种策略可使您像修改政策一样简单地修改开支报告的内容--当公司决定需要把餐费划分为早餐、午餐和晚餐项目，而且像上述修改政策一样简单地执行修改时--可编写一个实现该报告的新类，客户程序就会自动使用这个类。

计算服务器

　　开支报告的例子表示了客户机如何从服务器得到属性。属性可沿两个方向传递--客户机也可将新的类型传递给用户。最简单的例子就是如图2所示的计算服务器，该服务程序可执行任意任务，这样整个企业内的客户机都能利用高端或专用计算机。

任务由一个简单的本地(非远程)接口定义：
public interface Task {
Object run();
}
运行时，它就会进行一些计算，并返回一个包含结果的对象。这完全是一般性的任务--几乎所有计算任务都可在这个接口下实现。远程接口ComputeServer也同样简单：
import java.rmi.*;
public interface ComputeServer extends Remote {
Object compute(Task task) throws RemoteException;
}
这个远程接口的唯一目的就是使客户机创建一个Task (任务)对象，并把它发送给服务器执行，最后返回结果。该服务器的基本实现如下：
import java.rmi.*;
import java.rmi.server.*;
public class ComputeServerImpl
extends UnicastRemoteObject
implements ComputeServer
{
public ComputeServerImpl() throws RemoteException { }
public Object compute(Task task) {
return task.run();
}
public static void main(String[] args) throws Exception {
// use the default, restrictive security manager
System.setSecurityManager(new RMISecurityManager());
ComputeServerImpl server = new ComputeServerImpl();
Naming.rebind("ComputeServer", server);
System.out.println("Ready to receive tasks");
return;
}
}

　　如果您看一看compute方法就会发现，它非常简单。它只是接受传递给它的对象，并返回计算的结果。main方法包括服务器的启动代码--它安装了RMI的缺省安全管理程序，以防止他人存取本地系统，并创建可处理进入的请求的ComputeServerImpl对象，并将其与名字"ComputeServer"关联。这时，服务器已经准备好接收要执行的任务，而main 也完成了其设置。
如上所述，这实际上是一种全面和实用的服务。系统可以得到改进，比如，可添加要计算的参数，从而对使用服务程序的部门进行计费。但在很多情况下，上述接口和及其实现允许使用高端计算机进行远程计算。这又明了RMI的简单性--如果您键入上述类，对其进行编译，并启动服务程序，您就拥有了能执行任意任务的运行计算服务器。

　　下面介绍一个使用这种计算服务的例子。假定您购买了一个能运行大量计算操作应用程序的非常高端的系统。管理员可在该系统上启动一个Java虚拟机，运行ComputeServerImpl对象。该对象现在就可接受要运行的任务。

现在假定一个小组准备通过一组数据培训一个神经网络，以帮助制订采购策略。他们可以采用的步骤如下：

　　定义一个类--暂且称之为PurchaseNet。它能接受一组数据，并运行培训数据，返回一个经过培训的神经网络。PurchaseNet 将实现Task (任务)接口，并在其run方法中执行其工作。他们可能还需要一个Neuron类来描述所返回的网络中的节点，而且很可能需要其它类来描述处理过程。run方法将返回一个由一组经过培训的Neuron对象组成的NeuralNet对象。

当这些类被编写好并进行小规模测试时，用一个PurchaseNet 对象调用ComputeServer的compute方法。
当ComputeServerImpl对象中的RMI系统接收到作为进入参数的 PurchaseNet对象时，它就下载PurchaseNet的实现，并调用该服务器的compute方法，并把该对象作为Task (任务)参数。
Task，也就是PurchaseNet对象，将开始执行其执行程序。当执行程序需要诸如Neuron和NeuralNet等新的类时，它们可根据需要下载。
所有计算都将在计算服务器上执行，而客户机线程则等待结果。(客户机系统上的另一个线程则会显示“正在等待”光标或使用Java的内置并行机制执行另一个任务 )。当运行返回其NeuralNet对象时，这个对象将作为compute 方法的结果被传递回客户机。
这不需要在服务器上安装其它软件--所有必须完成的任务都由各部门在其自己的计算机上完成，随后再根据需要传递给计算服务器主机。
这个简单的计算服务器体系结构为系统的分布式功能提供了功能强大的转换能力。一项任务的计算可以被转移到一个能为其提供最好支持的系统上完成。这样的系统可以被用来：

　　在ComputeServerImpl对象运行于有数据挖掘需要的主机上，支持数据挖掘应用程序。这样可使您轻松地把任何计算移动到数据所在的地方。
在从当前股票价格、发货信息或其它实时信息等外部资源获得直接数据的服务器上运行计算任务。
通过运行ComputeServer (接受进入的请求并将其转送到运行 ComputeServerImpl的负担最小的服务器上)的不同实现，而将任务分布在多个服务器上。
代理
因为RMI允许使用Java实现下载属性，所以您可使用RMI 编写代理系统。代理的最简单格式如下：

import java.rmi.*;
public interface AgentServer extends Remote {
void accept(Agent agent)
throws RemoteException, InvalidAgentException;
}
public interface Agent extends java.io.Serializable {
void run();
}
启动一个代理也就创建了实现Agent (代理)接口、找到服务器、激活接受该代理对象的类。该代理的执行程序将被下载到服务器上运行。accept方法将启动一个该代理的新线程，激活其run方法，然后返回，从而使该代理一直执行到run方法返回为止。代理可通过激活在另一台主机上运行的服务程序的accept方法而移植到该主机，而其本身则作为将被接受的代理来传递，并结束其在原来主机上的线程。
面向对象的代码重用与设计模式

　　面向对象的编程是一项允许代码重用的强大技术。很多企业组织都使用面向对象的编程来减轻创建程序的负担和提高系统的灵活性。RMI是完全面向对象的--信息被发送给远程对象，而且对象可以被传递和返回。

Design Patterns (设计模式)目前在描述面向对象设计的实践活动中获得了相当大的成功。首先是因为Design Patterns 的创新工作而使之大受欢迎，这些编程方式是一种正式描述解决某类特定问题的完整方法的途径。所有这些设计模式都依赖于创建一个或多个抽象概念，这些抽象概念允许不同的实现，从而允许和增强软件重用。软件重用是面向对象技术的主要优势，而设计模式则是促进重用的最受欢迎的技术之一。

所有设计模式都依赖面向对象的多态性--这是对象( 如Task )拥有多个实现的能力。算法的普通部分(如compute 方法)不必知道使用了哪个实现，它只需知道得到一个对象后应该对该对象采取什么操作。特别地，计算服务器就是Command (指令)模式的一个例子，它可使您将请求 (任务)表示为对象，并对其进行调度。

只有当包括执行程序在内的完整对象能在客户机和服务器之间传递时，才会存在这样的多态性。DCE和DCOM等传统的RPC系统以及CORBA等基于对象的RPC系统不能下载并执行程序，因为它们不能把真实对象作为参数传递，而只能传递数据。

　　RMI可传递包括执行程序在内的所有类型，所以您可以在分布式计算解决方案中，而不仅仅是本地计算中使用面向对象的编程--包括设计方式。如果没有RMI这样完全面向对象的系统，那么您就必须放弃很多分布式计算系统中的设计方式--以及面向对象的软件重用的其它形式。

本文的讨论也很精彩，浏览讨论>>

JavaEye推荐

[原]BIRT 2.2.2 运行时使用已有的java.sql.Connection来生成报表

咖啡舞者 — Tue, 10 Jun 2008 16:49:21 +0800

作者: 咖啡舞者链接：http://07360591.javaeye.com/blog/201840 发表时间: 2008年06月10日

声明：本文系JavaEye网站发布的原创博客文章，未经作者书面许可，严禁任何网站转载本文，否则必将追究法律责任！

注：本文实现的思路不是原创，思路原文来自：

http://birtworld.blogspot.com/2005/12/using-supplied-connection-with-birt.html

本文将介绍BIRT2.2 详细的扩展与配置：

在ECLIPSE中新建一个工程 new-> Bussiness Intelligence Report Tools -> Web Project 名字：MyBirt

并设置好服务器信息（本文选用Tomcat5.5、JDK1.5）。

建好工程以后，需要添家JDBC驱动程序到报表引擎中，本例连接ORACLE，因此将ORACLE的JDBC驱动包复制到工程站点下的 /WEB-INF/platform/plugins/org.eclipse.birt.report.data.oda.jdbc_xxxxxxx/drivers目录下。

接下来就是继承OdaJdbcDriver类了，再此之前需要在ClassPath中Add oda-jdbc.jar 和 org.eclipse.datatools.connectivity.oda_xxxxxxxxxxxx.jar这两个包，前者位于上边提到的drivers路径的上一级，后着则在plugins下。新建一个Class：MyJdbcDriver，指定到某个包路径下，代码如下：

package com.wenmin.birt.data.oda.jdbc;

import org.eclipse.birt.report.data.oda.jdbc.OdaJdbcDriver;
import java.sql.Connection;
import java.util.HashMap;
import java.util.Properties;

import org.eclipse.birt.report.data.oda.jdbc.*;
import org.eclipse.datatools.connectivity.oda.IConnection;
import org.eclipse.datatools.connectivity.oda.OdaException;

public class MyJdbcDriver extends OdaJdbcDriver 
{

	private Connection passedInConnection;
	public static final String DATASOURCE_KEY_CONNECTION = "com.wenmin.birt.data.odb.jdbc.MyJdbcDriver";
	
	public void setAppContext( Object context ) throws OdaException
	{
	    HashMap ctx = (HashMap)context;
	    passedInConnection = (java.sql.Connection)ctx.get(DATASOURCE_KEY_CONNECTION);
	
	}	
	
	public IConnection getConnection(String connectionClassName) throws OdaException
	{
		if( passedInConnection != null){
			return new appContextDBConnection();
		}else{
			return new org.eclipse.birt.report.data.oda.jdbc.Connection();
		}
	}
	


	private class appContextDBConnection extends org.eclipse.birt.report.data.oda.jdbc.Connection
	{
	
			
		public void open(Properties connProperties) throws OdaException
		{
			super.jdbcConn = passedInConnection;			
		
		}
		
		public void close( ) throws OdaException
		{
			if ( jdbcConn == null )
			{
				return;
			}
			//should have call to return connection to the pool
			jdbcConn = null;						
		}				
		
		
		
	}
}

OK，接下来我们来打个包，利用ECLIPSE EXPORT一个 jar包，（“怎么做？”，“。。。拖下去，暴头！”）。

本例导出包名字为：cst_driver.jar，拷贝到/WEB-INF/platform/plugins/org.eclipse.birt.report.data.oda.jdbc_xxxxxxx/目录下。

最后就是修改配置文件，第一个需要改的文件plugin.xml位于 /WEB-INF/platform/plugins/org.eclipse.birt.report.data.oda.jdbc_xxxxxxx/目录下

找到如下节点：

...

      
....

修改为：

...

      
...

其他内容不需要改变。

然后在META-INF下的MANIFEST.MF中找到如下位置，添加刚才导出的包cst_driver.jar

Bundle-ClassPath: oda-jdbc.jar,derby.jar,cst_driver.jar

大功告成，接下来在程序中使用：

//....   
     HashMap contextMap = new HashMap();

    //...
     contextMap.put(MyJdbcDriver.DATASOURCE_KEY_CONNECTION, conn);  //conn为系统中获得的数据库连接
    task.setAppContext( contextMap );   //IRunAndRenderTask 
//...

这样，无论在设计时指定了什么数据源，都会在运行时通过已有的conn连接数据库了。

由于是这两天才接触的BIRT，文章有不足之处还请多多指正，谢谢。

本文的讨论也很精彩，浏览讨论>>

JavaEye推荐

BIRT Report Engine API

咖啡舞者 — Thu, 05 Jun 2008 16:20:40 +0800

作者: 咖啡舞者链接：http://07360591.javaeye.com/blog/200560 发表时间: 2008年06月05日

声明：本文系JavaEye网站发布的原创博客文章，未经作者书面许可，严禁任何网站转载本文，否则必将追究法律责任！

Report Engine API

Background

Installing the Engine

Configuring JDBC Drivers

API Overview

EngineConfig

ReportEngine

IReportRunnable

IReportDocument

IEngineTask

IDataExtractionTask

IGetParameterDefinitionTask

IRenderTask

IRunTask

IRunAndRenderTask

Miscellaneous

Emitter Configuration

BIRT Wiki RE API Examples

Background

The BIRT Report Engine API (RE API) allows you to integrate the run-time part of BIRT into your application. This may mean integrating into a stand alone Java application, deploying as part of a servlet or embedding it within an RCP application. The engine supports the following operations:

Discover the set of parameters defined for a report.
Get the default values for parameters.
Run a report to produce HTML/Paginated HTML, WORD, XLS, PS, or PDF output.
Fetch an image or chart for a report.
Export Report data to CSV
Retrieve TOCs, Bookmarks, etc

The report engine supports extensions for custom report items, data access, and custom output formats. Extensions are discussed elsewhere. This section will focus on how your application integrates with the report engine.

Installing the Engine

The first step is to download, install, and configure the BIRT engine. The engine is more than just a simple JAR file; it also includes a set of extensions (plug-ins), and a set of data drivers.

First download the Report Engine from the Eclipse download site.
This file will be named birt-runtime-version.zip.
Unzip this file into a directory, such as c:\birtruntime.
When you set the Engine Home, which is explained later, use C:/birtruntime/birt-runtime-version/ReportEngine as the value.
Add the jars in the ReportEngine/lib directory to your classpath/buildpath.

Note that if you are using the RE API within an RCP/Eclipse application these steps are not needed. Just add the RE API plugins to your application and call the needed functions.

The BIRT Viewer sample is also bundled with the Report Engine download. It is located under the WebViewerExample directory. If you decide to use this example, see Viewer Setup for an explanation. The Viewer uses the RE API to generate reports within the context of a servlet. It provides additional features, such as printing, TOCs, Page controls, etc. Before using the RE API, verify that the Viewer is not applicable to your application.

Engine Source

If you prefer to work directly with the BIRT source code, the Engine API is in the org.eclipse.birt.report.engine project within Eclipse CVS Eclipse CVS. The source is also available from the BIRT site in one package (the BIRT Source Code Package), which can be downloaded from the download site.

Javadoc

This page provides an overview of the engine. To do actual development, consult the Engine Javadoc. These docs are available within BIRT Help.

Configuring JDBC Drivers

You must configure the engine to include any JDBC drivers that you need.

To do this, copy the driver jar file to the ReportEngineInstall/birt-runtime-version/ReportEngine/plugins/org.eclipse.birt.report.data.oda.jdbc_version/drivers Directory.

API Overview

The following are the key steps to use the API, identifying the classes and interfaces you use for each step.

Create an instance of EngineConfig to set options for the report engine.
Set the Engine Home and start the Platform (Loads the plug-ins). If you are using the RE API in plugin format there is no need to set BIRT Home. If you are using the RE API from within a servlet, be sure to read about PlatformServletContext later on this page.
Create an instance of the ReportEngine class. You can use this object to perform multiple tasks.
Open a report design using one of the openReport( ) methods of ReportEngine.
Obtain information about report parameters using IGetParameterDefinitionTask. This is only needed if you want to build a custom parameter page or collect parameter definition information. The IRunTask and the IRunAndRenderTask interfaces have methods for setting parameter values.
Run and render a report using IRunAndRenderReportTask or IRunTask and IRenderTask.
Repeat steps 4-6 for the next report.
When done, call shutdown( ) on your engine instance. If using the engine in a servlet shudown the engine when the servlet shuts down.

The following sections describe the primary Engine classes in detail. The Engine API includes a number of secondary helper classes referenced within each description. The diagram below, serves as an overview of the classes needed to accomplish a given task.

EngineConfig

Use the EngineConfig class to set global options for the report engine as a whole. Use it to specify the location of engine plug-ins, the location of data drivers, and to add application-wide scriptable objects.

>
EngineConfig config = new EngineConfig( );
config.setEngineHome( "put engine path here" );

The engine home should be set to installedlocation/birt-runtime-version/ReportEngine when deployed as a stand alone Java Application. See the wiki examples for Servlet and RCP deployment.

Other functions of interest within this class are:

setLogConfig(String directoryName, Level level)
This call sets the Log directory name and level (OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST and ALL)
Setting directoryName to null will log to stdout.

ReportEngine

The ReportEngine class represents the BIRT Report Engine. There is a significant cost associated with creating an engine instance, due primarily to the cost of loading extensions. Therefore, each application should create just one ReportEngine instance and use it to run multiple reports. This is important to remember when deploying the engine in a servlet as well.

The report engine is created through a factory supplied by the Platform. Before creating the engine, you should start the Platform, which will load the appropriate plug-ins. This is done by calling Platform.startup(config) that takes an EngineConfig object as argument. After using the engine, call Plaform.shutdown()( ) function to do clean up work, which includes unloading the extensions.

try{
	final config = new EngineConfig( );
	config.setEngineHome( "C:\birt-runtime-2_1_0\birt-runtime-2_1_0\ReportEngine" );
	config.setLogConfig(c:/temp, Level.FINE);
			
	Platform.startup( config );  //If using RE API in Eclipse/RCP application this is not needed.
	IReportEngineFactory factory = (IReportEngineFactory) Platform
			.createFactoryObject( IReportEngineFactory.EXTENSION_REPORT_ENGINE_FACTORY );
	IReportEngine engine = factory.createReportEngine( config );
	engine.changeLogLevel( Level.WARNING );
			
}catch( Exception ex){
	ex.printStackTrace();
}
// Run reports, etc.
...

// destroy the engine.
try
{
	engine.destroy();
	Platform.shutdown();    
}
catch ( EngineException e1 )
{
    // Ignore
}

Other functions of interest within this class are:

engine.changeLogLevel(java.util.logging.Level.FINE);
Change engine log level (OFF, SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST and ALL)

IReportRunnable

BIRT report designs are stored as XML files. By default the extension is rptdesign.
To work with the report design in the engine, you must first load the report using one of the openDesign( ) methods in the ReportEngine class.

The report design open methods return a IReportRunnable instance that represents the engine's view of the report design.

IReportRunnable report = engine.openReportDesign( name );

Note that BIRT supplies many options for opening reports such as the filename or an input stream. Use the returned object to obtain parameter data or run the report.
The class provides methods for getting report properties such as the title, author and so on. It also provides methods for getting images embedded (stored) within the report design. If your application requires more information about the design, you can obtain a Design Engine report handle, then use the BIRT Design Engine API to traverse the report design.

IReportDocument

BIRT optionally can store reports in an intermediate format, after generation and before rendering. This document, with the default extension rptdocument, can be manipulated with the IReportDocument interface. The Engine will create this document when the runTask is used. The BIRT viewer uses this format to do pagination, TOCs, CSV extraction, bookmarks, etc. When finished with a IReportDocument, be sure to close it, with the close() method.

The Engine's openDocument method returns a IReportDocument that represents the intermediate report document.

The example below illustrates getting the TOC from the report document, after the runTask is used to generate the report.

IReportDocument ird = engine.openReportDocument("c:/work/test/TOCTest.rptdocument");
//get root node
TOCNode td = ird.findTOC(null);
List children = td.getChildren( );
//Loop through Top Level Children
if ( children != null && children.size( ) > 0 )
{
	for ( int i = 0; i < children.size( ); i++ )
	{
		TOCNode child = ( TOCNode ) children.get( i );
		System.out.println( "Node ID " + child.getNodeID());
		System.out.println( "Node Display String " + child.getDisplayString());
		System.out.println( "Node Bookmark " + child.getBookmark());
			
	}
}

IEngineTask

BIRT reports support scripting. Operations that execute scripts require a scripting context. Report operations also require a locale. BIRT Engine tasks provide the framework for managing the scripting context, report locales and so on. In general, if an operation requires neither a script context nor a locale, it will appear as a method on the engine or the report design. However, if the operation does require these items, then a task class represents the operation.

For example, opening a design file or retrieving an image in the design file does not require setting up a scripting context. Other operations, such as retrieving default parameters, retrieving a dynamic selection list, and running and rendering a report, all support scripting, require a scripting context, and are represented as tasks.

Create tasks using the factory methods on the ReportEngine class. The supported Tasks are shown below:

engine.createDataExtractionTask();
engine.createGetParameterDefinitionTask();
engine.createRenderTask();
engine.createRunTask();
engine.createRunAndRenderTask();

IDataExtractionTask

Use this task to extract data from a report document. The BIRT viewer uses this class to extract report data into CSV format. This class supports extracting data from the report document by specifying the result set and columns you would like to have extracted.
From the Viewer code

dataTask.selectResultSet( resultSetName );
dataTask.selectColumns( columnNames );
dataTask.setLocale( locale );

Below is an example that uses the Data Extraction Task to extract the first two columns of data.

//Open previously created report document
IReportDocument iReportDocument = engine.openReportDocument("c:/work/test/TOCTest.rptdocument");

//Create Data Extraction Task		
IDataExtractionTask iDataExtract = engine.createDataExtractionTask(iReportDocument);

//Get list of result sets		
ArrayList resultSetList = (ArrayList)iDataExtract.getResultSetList( );

//Choose first result set
IResultSetItem resultItem = (IResultSetItem)resultSetList.get( 0 );
String dispName = resultItem.getResultSetName( );
iDataExtract.selectResultSet( dispName );

IExtractionResults iExtractResults = iDataExtract.extract();
IDataIterator iData = null;
try{
	if ( iExtractResults != null )
	{
		iData = iExtractResults.nextResultIterator( );

		//iterate through the results
		if ( iData != null  ){
			while ( iData.next( ) )
			{	
				Object objColumn1;
			    Object objColumn2;
				try{
					objColumn1 = iData.getValue(0);
				}catch(DataException e){
					objColumn1 = new String("");
				}
				try{
					objColumn2 = iData.getValue(1);
				}catch(DataException e){
					objColumn2 = new String("");
				}
					System.out.println( objColumn1 + " , " + objColumn2 );
			}
			iData.close();
		}
	}
}catch( Exception e){
		e.printStackTrace();
}

iDataExtract.close();

IGetParameterDefinitionTask

Use this task to obtain information about parameters. Parameter default values are expressions, and so a scripting context (represented by the task) is required. Parameter definitions provide access to the parameter definition information that the report designer entered at design time. If a parameter has custom XML or user-defined properties defined, then these are also available. Parameters can be organized into groups. Your application has the choice of retrieving the parameters organized by group (as they should be displayed to the user), or in ungrouped form (useful for creating a programmatic interface.)

The IParameterGroupDefn and IScalarParameterDefn interfaces provide information about parameter groups and individual parameters.

The following example opens a report design and iterates through the parameters and parameter groups. If a List Box parameter is found, which is not in a group, the selection values are retrieved.

//Open a report design 
IReportRunnable design = engine.openReportDesign("C:/work/test/parameters.rptdesign"); 
		
IGetParameterDefinitionTask task = engine.createGetParameterDefinitionTask( design );
Collection params = task.getParameterDefns( true );

Iterator iter = params.iterator( );
//Iterate over all parameters
while ( iter.hasNext( ) )
{
	IParameterDefnBase param = (IParameterDefnBase) iter.next( );
	//Group section found
	if ( param instanceof IParameterGroupDefn )
	{
		//Get Group Name
		IParameterGroupDefn group = (IParameterGroupDefn) param;
		System.out.println( "Parameter Group: " + group.getName( ) );
		
		//Get the parameters within a group
		Iterator i2 = group.getContents( ).iterator( );
		while ( i2.hasNext( ) )
		{
			IScalarParameterDefn scalar = (IScalarParameterDefn) i2.next( );
			System.out.println("	" + scalar.getName());
		}
		        
	}
	else
	{
		//Parameters are not in a group
		IScalarParameterDefn scalar = (IScalarParameterDefn) param;
		System.out.println(param.getName());
		
		//Parameter is a List Box
		if(scalar.getControlType() ==  IScalarParameterDefn.LIST_BOX)
		{
		    Collection selectionList = task.getSelectionList( param.getName() );
		    //Selection contains data    
			if ( selectionList != null )
			{
				for ( Iterator sliter = selectionList.iterator( ); sliter.hasNext( ); )
				{
					//Print out the selection choices
					IParameterSelectionChoice selectionItem = (IParameterSelectionChoice) sliter.next( );
					String value = (String)selectionItem.getValue( );
					String label = selectionItem.getLabel( );
					System.out.println( label + "--" + value);
				}
			}		        
		}   
	}
}
		
task.close();

Use the IGetParameterDefinitionTask class to evaluate the default value for a parameter. The parameter default value is an expression, and the task provides the required execution context.

IScalarParameterDefn param = ...;
IGetParameterDefinitionTask task = ...;
Object value = task.getDefaultValue( param );

IRenderTask

Use this task to render a report document to a specific output (eg, HTML, PDF, ...). This task expects the document to exist, which means it has been generated with the RunTask engine task. This class renders the report, based on the supplied page range, page number or all if no page is specified.

The following example renders the first two pages of the "Pages" report document. You will notice that it renders the two pages as one page of HTML.

//Open a report document 
IReportDocument iReportDocument = engine.openReportDocument("c:/work/test/Pages.rptdocument");
//Create Render Task
IRenderTask task = engine.createRenderTask(iReportDocument);
//Set parent classloader report engine
task.getAppContext().put(EngineConstants.APPCONTEXT_CLASSLOADER_KEY, RenderTaskExample.class.getClassLoader()); 

IRenderOption options = new RenderOption();		
options.setOutputFormat("html");
options.setOutputFileName("output/resample/eventorder.html");
	
			
if( options.getOutputFormat().equalsIgnoreCase("html")){
	HTMLRenderOption htmlOptions = new HTMLRenderOption( options);
	htmlOptions.setImageDirectory("output/image");
	htmlOptions.setHtmlPagination(false);
	//set this if you want your image source url to be altered
	//If using the setBaseImageURL, make sure to set image handler to HTMLServerImageHandler
	htmlOptions.setBaseImageURL("http://myhost/prependme?image=");
			
	htmlOptions.setHtmlRtLFlag(false);
	htmlOptions.setEmbeddable(false);
}else if( options.getOutputFormat().equalsIgnoreCase("pdf") ){
			
	PDFRenderOption pdfOptions = new PDFRenderOption( options );
	pdfOptions.setOption( IPDFRenderOption.FIT_TO_PAGE, new Boolean(true) );
	pdfOptions.setOption( IPDFRenderOption.PAGEBREAK_PAGINATION_ONLY, new Boolean(true) );

}
//Use this method if you want to provide your own action handler
options.setActionHandler(new MyActionHandler());

//file based images
//options.setImageHandler(new HTMLCompleteImageHandler())
//Web based images.  Allows setBaseImageURL to prepend to img src tag
options.setImageHandler(new HTMLServerImageHandler());
		
IRenderTask task = engine.createRenderTask(document); 		
task.setRenderOption(options);
task.setPageRange("1-2");
task.render();
iReportDocument.close();

IRunTask

Use this task to run a report and generate a report document, which is saved to disk. The report document can then be used with the IRenderTask to support features such as paging.

The following example simply creates a report document and saves it to disk.

//Open a report design 
IReportRunnable design = engine.openReportDesign("C:/work/test/MyOrders.rptdesign"); 
		
//Create task to run the report - use the task to execute the report and save to disk.
IRunTask task = engine.createRunTask(design); 
//Set parent classloader for engine
task.getAppContext().put(EngineConstants.APPCONTEXT_CLASSLOADER_KEY, RunTaskExample.class.getClassLoader()); 
					
//run the report and destroy the engine
task.run("c:/work/test/MyOrders.rptdocument");		

task.close();

IRunAndRenderTask

Use this task to run a report and output it to one of the supported output formats. This task does not create a report document. Create a new task for each report that you run.

Reports may take parameters. The IRunAndRenderReportTask takes parameter values as a HashMap or you can set them individually. The IRunAndRenderReportTask provides the validateParameters( ) method to validate the parameter values before you run the report.

//Open the report design
IReportRunnable design = engine.openReportDesign("Reports/TopNPercent.rptdesign"); 
	

//Create task to run and render the report,
IRunAndRenderTask task = engine.createRunAndRenderTask(design); 
//Set parent classloader for engine
task.getAppContext().put(EngineConstants.APPCONTEXT_CLASSLOADER_KEY, RunAndRenderTaskExample.class.getClassLoader()); 
		
//Set parameter values and validate
task.setParameterValue("Top Percentage", (new Integer(3)));;
task.setParameterValue("Top Count", (new Integer(5)));
task.validateParameters();
				
//Setup rendering to HTML
HTMLRenderOption options = new HTMLRenderOption();		
options.setOutputFileName("output/resample/TopNPercent.html");
options.setOutputFormat("html");
//Setting this to true removes html and body tags
options.setEmbeddable(false);
		
task.setRenderOption(options);
//run and render report
task.run();
task.close();

Miscellaneous

Described below are some miscellaneous items that bear mentioning when using the BIRT Report Engine API

Adding Script Objects

BIRT's script engine supports adding Java objects at the API level. If you wish the Java object to be available to the Report, retrieve the application context at the EngineConfig or Task level and add the object to the Map. For example, adding a Java object to the task.

Add the following code to your task.

MyJavaObject jo = new MyJavaObject();
task.getAppContext().put("MyJavaScriptItem", jo);

Now within the the script editor, you can reference your Java Object as follows:

testMyJavaObject = MyJavaScriptItem.getMyMethod();

Rendering to an Output Stream

When rendering a report it may be desirable to output the report to an output stream, such as HttpServletResponse. To do this modify your RenderOption instance to use setOutputStream instead of setOutputFileName. For example,

public void webReport( HttpServletResponse response )
{
.
.
.
//Set rendering options 
HTMLRenderOption options = new HTMLRenderOption();
options.setOutputStream(response);
task.setRenderOption(options);		
//run the report
task.run();
}

IPlatformContext - Web Based Plugin Loading

By default BIRT loads plug-ins located in the BIRT_HOME/plugins directory. The plug-ins loaded provide functionality for connecting to data sources, emitters (eg, PDF, WORD, XLS, HTML ...), and chart rendering. BIRT_HOME in the examples on this page is set using the setEngineHome method of the EngineConfig class. BIRT loads these plug-ins using the Java File API.

This method is usually sufficient. If deployed to a web application, the developer can usually call ServletContext.getRealPath to retrieve the real path and set the BIRT_HOME accordingly. This can present a problem when deploying to a war file. Certain application servers will return null when getRealPath is called. This will result in the plug-ins not getting loaded.

The IPlatformContext interface describes the methods needed to load the resources required by the BIRT runtime. Within BIRT there are two implementations of this interface, PlatformFileContext() and PlatformServletContext(). The Platform Context is set using the setEngineContext method of the EngineConfig class. If this method is not called it defaults to PlaformFileContext() and uses the Java File API to load the resources. The PlatformServletContext class uses Resource based operations. So if you are deploying an application to the Web that uses the BIRT API and it is not contained in a war you can use the default and set your engine home to something similar to:

config.setEngineHome( servletContext.getRealPath("/WEB-INF"));

The BIRT Viewer application will load the plug-ins from /WEB-INF/Plugins directory. If you deploy your application in a war, setup your code like:

//this causes the plug-in loader to look in the current directory.
config.setEngineHome("");
//Using the PlatformServletContext will cause the OSGi loader to look for the
//plug-ins in the WEB-INF/Platform directory.  If this directory
//does not exist create it. 
//Next copy the plug-ins directory from the ReportEngine directory to
//the WEB-INF/Platform/ directory.
IPlatformContext context = new PlatformServletContext( sc );
config.setPlatformContext( context );

Embedding Report Output

If you need to embed your report output into an existing web page you can use the options.setEmbeddable(true); method. This will remove the and tags in the generated report. For example,

public void embedReport( HttpServletResponse response )
{
.
.
.
//Set rendering options 
HTMLRenderOption options = new HTMLRenderOption();
options.setOutputStream(response);
options.setEmbeddable(true);
task.setRenderOption(options);		
//run the report
task.run();
}

Emitter Configuration

An "emitter" is the component of the report engine that produces output. BIRT provides many emitters such as HTML, XLS and PDF. To configure emitter options you need to use the RenderOption class. In some of the examples above this was done, with code similar to the following:

IRenderOption options = new RenderOption();		
options.setOutputFormat("html");
options.setOutputFileName("output/resample/eventorder.html");

BIRT also provides an extended RenderOption class for the PDF and HTML emitters (PDFRenderOption and HTMLRenderOption). The PDFRenderOption class provides methods for handling fonts and the HTMLRenderOption class provides methods for handling images, url encoding, and other html specific settings. You may need to configure the HTML emitter to manage images.
BIRT supports several image types:

Images referenced using a URL
Embedded images
Images created to represent charts
Images from BLOB types

Your application must have a policy for handling images in HTML. URL-based images are usually no problem. However, you'll need to handle the others. The IHTMLImageHandler interface defines the policy. The BIRT Engine provides two default implementations:

HTMLCompleteImageHandler: used to write images to disk when rendering a report to produce an HTML file on disk.
HTMLServerImageHandler: used to handle images for an engine running in an app server. This class is used by the BIRT example web viewer.

When you instantiate a EngineConfig class the HTMLCompleteImageHandler class is used by default. Images will be created in your temporary files location (ie C:\Documents and Settings\User\Local Settings\Temp). If this is not desired you can use the HTMLRenderOption class to change this location.

HTMLRenderOption htmlOptions = new HTMLRenderOption( options);
htmlOptions.setImageDirectory("output/image");

Setting the Image Directory instructs the RE API to store images, used within the report output, in that directory. If your emitter is setup with the standard HTMLCompleteImageHandler, the output image src attribute will point to this directory using the File protocol. If your emitter is configured with the HTMLServerImageHandler, you can specify an image base URL using the HTMLRenderOption class. The engine will prepend all images with this URL in the src attribute of the report output.

HTMLRenderOption options = new HTMLRenderOption();		
options.setOutputFileName("output/resample/TopNPercent.html");
options.setOutputFormat("html");
options.setImageDirectory("C:\apps\apache-tomcat-5.5.20\webapps\2.2\images");
options.setBaseImageURL("http://localhost:8080/2.2/images/");		
options.setImageHandler(new HTMLServerImageHandler());
task.setRenderOption(options);

You can also create your own implementation of IHTMLImageHandler if the above don't meet your needs.

If your code is going to be run in a servlet, please review the ReportEngineService.java code in CVS ReportEngineService.java The BIRT Viewer uses this class to configure the engine. The constructor for the ReportEngineService uses the HTMLServerImageHandler class, which in turn reads Image locations from the web.xml file.

本文的讨论也很精彩，浏览讨论>>

JavaEye推荐

BIRT部署并利用API生成PDF

咖啡舞者 — Thu, 05 Jun 2008 14:24:49 +0800

作者: 咖啡舞者链接：http://07360591.javaeye.com/blog/200507 发表时间: 2008年06月05日

声明：本文系JavaEye网站发布的原创博客文章，未经作者书面许可，严禁任何网站转载本文，否则必将追究法律责任！

注：本文转自 http://blog.csdn.net/xujiaqiang/archive/2008/01/19/2052789.aspx

感谢作者分享。

Birt报表设计步骤：

1、下载birt all in one 2.2.1.1，包含eclipse，解开下载文件
启动eclipse，必须使用JDK1.5启动eclipse，否则新建工程对话框中没有birt的相关选项

2、新建report project和report
打开data explorer视图，新建一个data sources，定义数据库连接driver/url/用户名/密码，在"Manage Drivers..."中把jdbc的jar加进来

3、新建Report Parameter，设置参数名称、类型，参数值将来通过url传递或使用程序方式赋值

4、新建data sets，设置Query，即preparedStatement语句，设置data set的Pameters，即reparedStatement中的“?”，使之和report parameter关联；如果data set的Parameter的值不是来自于Report Parameter，例如来自另外一个data set，可不设置关联，而在报表内容中设置和其它data set字段的关联（见步骤8）

5、如果data set对应的sql是动态生成的，可以设置“property Binding”，在Query Text中输入sql和表达式，其中可以使用Report Parameter和javascript语句，运行时将执行Property Binding中的Query Text，而不执行Query中的preparedStatement，但是Query中的preparedStatement在设计报表时还是有用的，因为可以看到运行结果的字段列表，只要preparedStatement和Query Text返回相同的字段即可

6、将定义好的data set拖动到设计界面上，会自动在报表放置一个Table

7、如要对table的某列合计，从Palette视图中拖一个“Aggregation”到设计界面

8、如要Master-Sleve报表，则在Table中再放置一个Table。例如一个data set是客户基本信息，每个客户一条记录，另一个data set是客户交易明细，每个客户可能有多条记录，则先将客户基本信息的data set拖置设计界面，会自动放置一个Table，然后将客户交易明细的data set拖置前一个Table中适当位置，即生成一个Table中的Table。选中交易明细的Table，打开Property Editor视图，在binding栏中，选择交易明细的data set，按“Dataset Parameter Binding...”，选择“CUST_ID"字段，将其和客户基本信息data set的CUST_ID关联起来（row["CUST_ID"]）

9、按需要调整报表的样式，从eclipse工具栏中选择“view report in web viewer”，如果设置了Report Parameter，会出现一个对话框，要求输入Report Parameter的值，按确定后生成报表内容

10、在web viewer中，鼠标右建点按生成的报表，选“属性”，获取url，开一个空白IE，复制url到地址栏，在url最后用“&参数名=参数值”方式，把Report Parameter加进url，按回车，直接出现报表结果，不再出现报表参数输入对话框。还可以pdf/doc/html等格式预览生成的报表

Birt报表部署步骤：

部署设计好的报表很简单，只需要下载Birt runtime，将Birt runtime部署为一个web应用，报表设计文件复制到该应用的根目录即可。为方便起见，以下将Birt runtime部属为一个独立的应用，当然也可以将Birt runtime整合到你的web应用中

1、下载birt runtime 2.2.1.1，解开下载文件
2、将birt rumtime解开后的目录下的部署为一个web应用，使用JDK1.4.2或以上版本
3、将报表设计步骤中生成的设计文件（*.retdesing文件）复制到web应用所在目录
4、确保以下文件在WEB-INF/lib目录下存在，如果没有，从all in one中搜索复制过来
       com.ibm.icu_3.6.1.v20070906.jar
       coreapi.jar
       engineapi.jar
       scriptapi.jar
5、将jdbc的jar或zip文件复制到WEB-INF\platform\plugins\org.eclipse.birt.report.data.oda.jdbc_2.2.1.r22x_v20070919\drivers目录下
6、删除WEB-INF\platform\org.eclipse.birt.report.data.oda.sampledb_2.2.1.r22x_v20070919目录（示例数据库，没什么用处），否则生成报表时有不必要的警告信息出现
7、启动web server，修改设计步骤第10步获得的url，使IP/端口/web应用名称符合你的Birt runtime部署，在IE中可以查看报表内容

使用Birt提供API以程序方式生成报表结果，例如生成PDF格式的报表结果，代码片段如下：

import java.util.HashMap;
import java.util.logging.Level;

import java.io.OutputStream;
import java.io.FileOutputStream;
import java.io.ByteArrayOutputStream;

import org.eclipse.birt.core.framework.Platform;
import org.eclipse.birt.report.engine.api.EngineConfig;
import org.eclipse.birt.report.engine.api.EngineConstants;
import org.eclipse.birt.report.engine.api.EngineException;
import org.eclipse.birt.report.engine.api.IReportEngine;
import org.eclipse.birt.report.engine.api.IReportEngineFactory;
import org.eclipse.birt.report.engine.api.IReportRunnable;
import org.eclipse.birt.report.engine.api.IRunAndRenderTask;
import org.eclipse.birt.report.engine.api.PDFRenderOption;

public class PDFReportServiceAccess
{
    /** *//** 初始化的状态 */
    protected static boolean initStatus = false;

    private static IReportEngine engine = null;

    private static EngineConfig config = null;
    
    private static IReportRunnable design = null;
    
    private static PDFRenderOption ro = null;

    /** *//** 初始化资源 */
    public void initilize()
    {
    if ( initStatus == true )
        return;

    try
    {
        config = new EngineConfig();
        config.setEngineHome( "C:/projects/birt/WEB-INF/platform" );  //birt runtime web应用中的报表引擎目录
        config.setLogConfig( "C:/projects/birt/logs", Level.FINE );

        Platform.startup( config );
        IReportEngineFactory factory = ( IReportEngineFactory ) Platform
            .createFactoryObject( IReportEngineFactory.EXTENSION_REPORT_ENGINE_FACTORY );
        engine = factory.createReportEngine( config );
        engine.changeLogLevel( Level.WARNING );

        ro = new PDFRenderOption();
      //  ro.setBaseURL( "http://localhost:8080/birt" ); //birt runtime web应用
        config.getEmitterConfigs().put( "pdf", ro ); //生成pdf格式

        initStatus = true;

    }
    catch ( Exception ex )
    {
        ex.printStackTrace();
        initStatus = false;
    }
    }

    /** *//** 释放资源 */
    public void release()
    {
    engine.shutdown();
    Platform.shutdown();

    initStatus = false;
    }

    protected OutputStream run( String filename, HashMap parameters ) throws EngineException
    {
    design = engine.openReportDesign( filename );
    
    // Create task to run and render the report,
    IRunAndRenderTask task = engine.createRunAndRenderTask( design );
    HashMap contextMap = new HashMap();
    contextMap.put( EngineConstants.APPCONTEXT_PDF_RENDER_CONTEXT, ro );
    task.setAppContext( contextMap );
    task.setParameterValues( parameters );
    task.validateParameters();

    OutputStream os = new ByteArrayOutputStream();
    ro.setOutputStream( os );
    ro.setOutputFormat( "pdf" );
    task.setRenderOption( ro );

    task.run();
    task.close();

    return os;
    }

    /** *//**
         * 生成PDF格式报表,以OutputStream格式返回
         * 
         * @param filename 报表设计文件名全路径
         * @param parameters
         *                报表参数
         * @return ByteArrayOutputStream
         * @throws EngineException
         */
    public OutputStream call( String filename, HashMap parameters ) throws EngineException
    {
    initilize();
    OutputStream os = run( filename, parameters );
    release();
    
    return os;
    }

    /** *//**
         * @param args
         */
    public static void main( String[] args )
    {
    HashMap parameters = new HashMap();
                     //三个Report Parameters，名称必须在报表设计文件中预先定义好
    parameters.put( "begindate", "2004/01/01" );
    parameters.put( "enddate", "2007/12/31" );
    parameters.put(  "sql", " where cust_id = 1234567" );
    
    ByteArrayOutputStream bos = null;

    PDFReportServiceAccess ebr = new PDFReportServiceAccess();

    String filename = "C:/projects/birt/batch_report.rptdesign";
    try
    {
        bos = ( ByteArrayOutputStream ) ebr.call( filename, parameters );
        OutputStream fis = new FileOutputStream( "c:/test.pdf" );
        bos.writeTo( fis );
    }
    catch ( Exception e )
    {
        e.printStackTrace();
    }
    }

}

本文的讨论也很精彩，浏览讨论>>

JavaEye推荐