本系列的第2部分使用测试工具探索了IBM®Blueworks Live的代表性状态转移（REST）应用程序编程接口（API）。 第3部分展示了如何使用Shell命令快速获取有关通过REST API检索的Blueworks Live数据的信息。 尽管shell命令非常灵活和强大，但是该方法是技术性的，使用起来可能非常复杂。
第4部分展示了如何编写易于使用但可以处理通过REST API检索的数据的复杂处理的Java™应用程序。
Blueworks Live REST API文档包括Java代码模板，您可以将它们用作自己的项目的基础。 在示例下，您可以下载以下三个示例Java程序：
RestApiClientTemplate.java RestApiClientAuthTemplate.java RestApiClientPostTemplate.java该示例还提供了以下Java归档（JAR）文件，该文件是可与JavaScript Object Notation（JSON）对象一起使用的库：
json4j在Blueworks Live REST API文档中，您可以阅读有关编译和运行源代码的信息。 先决条件是在操作系统上进行Java安装（用于编译代码的Java开发工具包和用于运行代码的Java运行时环境）。
使用像Eclipse这样的集成开发环境（IDE），您可以修改Java代码或轻松编写自己的代码。 请参阅Eclipse下载网站。
以下各节描述如何创建可以直接作为桌面应用程序运行的Java程序。 另外，您可以将其扩展到服务器上运行的servlet，并从浏览器中调用它。
对于桌面应用程序开发，您需要Java开发人员专用的Eclipse IDE。 要将示例扩展到Servlet，请使用Eclipse IDE for Java EE Developers。
本教程没有深入研究使用Java和Eclipse的细节。 它假定您具有基本的Java编程知识。
使用Blueworks Live REST API文档中提供的示例Java模板，您可以使用三个Java文件：
RestApiClientTemplate.java RestApiClientAuthTemplate.java RestApiClientPostTemplate.java像在第2部分和第3部分中的示例一样，您首先使用/api/Auth资源。 RestApiClientAuthTemplate.java示例向您展示如何在Java中使用/api/Auth资源。 仔细研究一下Java代码，发现除了Blueworks Live URL之外，还设置了API资源，版本和登录信息。
修改登录数据（ REST_API_USERNAME和REST_API_PASSWORD ）以匹配您的Blueworks Live帐户，如以下示例所示：
private final static String REST_API_SERVER = "https://www.blueworkslive.com"; private final static String REST_API_CALL_AUTH = "/api/Auth"; private final static String REST_API_AUTH_VERSION = "20110917"; private final static String REST_API_USERNAME = "westphal@de.ibm.com"; private final static String REST_API_PASSWORD = "XXX";在这些设置之下，在main方法中，您将看到如何为API请求构建字符串以及如何建立连接，如以下示例所示：
StringBuilder authUrlBuilder = new StringBuilder(REST_API_SERVER); authUrlBuilder.append(REST_API_CALL_AUTH); authUrlBuilder.append("?version=").append(REST_API_AUTH_VERSION); HttpURLConnection restApiURLConnection = getRestApiConnection(authUrlBuilder.toString(), "GET");该代码的其余部分主要处理捕获潜在的错误情况。 以下命令提示符获取并打印API调用结果：
InputStream restApiStream = restApiURLConnection.getInputStream(); try { JSONObject authenticateResult = new JSONObject(restApiStream); String userStatus = (String) authenticateResult.get("result"); … JSONArray accounts = (JSONArray) authenticateResult.get("accounts"); for (Object account : accounts) { System.out.println("\t" + ((JSONObject) account).get("name")); } …请记住，在第2部分和第3部分中，存储在authenticateResult中的JSON结果类似于以下示例： {"result":"multiaccount","accounts":[{"id":"163a15e19f","name":"IBM70"},{"id":"3a480000","name":"IBMTechSales"},…
使用get()方法（例如get("accounts")提取所有相应的帐户对象。 使用get("name") ，将为每个帐户条目读取名称。 因此，程序的输出类似于以下示例：
IBM70 IBMTechSales …RestApiClientTemplate.java示例程序的结构类似于RestApiClientAuthTemplate.java示例程序，并打印用户名列表。
除了登录数据，您还必须定义一个有效的帐户名，如以下示例所示：
private final static String REST_API_ACCOUNT_NAME = "YYY";除版本外，此帐户名还用作请求中的附加参数，如以下示例所示：
StringBuilder appListUrlBuilder = new StringBuilder(REST_API_CALL_USERLIST); appListUrlBuilder.append("?version=").append(REST_API_USERLIST_VERSION); appListUrlBuilder.append("&account=").append(REST_API_ACCOUNT_NAME);您可以扩展输出以获取更多信息，如以下示例所示：
System..print("User name=" + user.get("name")); System..print(" email=" + user.get("email")); System..print(" license=" + user.get("license")); System..println("");如第2部分和第3部分中所述， www.blueworkslive.com服务器不是服务端点。 /api/Auth以外的任何请求都将转发到托管您帐户的服务器（例如，阿姆斯特丹的Blueworks Live服务器）。 最后一个示例RestApiClientPostTemplate.java处理从www.blueworkslive.com到您帐户的本地数据中心服务器的转发。 理想情况下，您只需确定一次该服务器，然后直接在设置中使用它即可。 但是，此Java示例中的实现方式使程序更加通用。
使用以下命令，程序首先调用/api/Auth资源，以从REST API调用结果中确定服务提供者地址（服务端点）：
String serviceProviderAddress = getServiceProviderAddress();然后，所确定的地址将代替www.blueworkslive.com用于任何连续的REST API调用。
示例Java应用程序使用/scr/api/Search资源发送搜索请求。 它交出参数，如以下示例所示，这些参数已简化：
StringBuilder appSearchUrlBuilder = new StringBuilder(serviceProviderAddress); appSearchUrlBuilder.append(REST_API_CALL_SEARCH); appSearchUrlBuilder.append("?version=").append(REST_API_SEARCH_VERSION); appSearchUrlBuilder.append("&account=").append(REST_API_ACCOUNT_NAME); appSearchUrlBuilder.append("&searchFieldName=").append("process_name"); appSearchUrlBuilder.append("&searchValue=").append("Hiring%20-%20Onboarding"); appSearchUrlBuilder.append("&returnFields=*");由于搜索词是资源请求的一部分，因此必须保护某些字符：它们必须使用特定的URL编码进行传递，这是一种在统一资源标识符中编码信息的机制。 需要此URL编码的字符在前面的代码示例中包括“ Hiring Onboarding的空格字符。 该空格必须表示为%20或+ 。 否则，您将收到以下错误消息作为响应： Error calling the Blueworks Live REST API: Bad Request
如果要手动输入搜索查询，则下表显示了某些字符的URL编码示例。 通常，编码以%开头，然后是字符的UTF-8编码的十六进制表示，这就是为什么这种类型的URL编码也称为百分比编码的原因。
此编码也适用于%通配符。 例如，如果要查找以Onboarding结尾的流程，则可以将%Onboarding作为搜索项，并使用编码进行编码，您必须像下面的示例一样编写它：
appSearchUrlBuilder.append("&searchValue=").append("%25Onboarding");您可以让Java自动进行编码，而不必手动进行编码。 您需要URLEncoder. encode () 使用"UTF-8"编码的URLEncoder. encode ()方法，如以下示例所示：
import java.net.URLEncoder; … appSearchUrlBuilder.append("&searchValue=").append(URLEncoder.encode("% Prozessübersicht", "UTF-8"));该样本搜索查询查找所有以Prozessübersicht结尾的过程 （德语为过程概述 ）。 该查询将自动转换为以下代码： … &searchValue=%25+Prozess%C3%BCbersicht …
github.com/BwlSamples中的代码示例提供了Java的示例实现，其中包括用例场景的文档：
用例1代码示例： github.com/BwlSamples/BwlFileDownloader 用例2代码示例： github.com/BwlSamples/BwlUserStats 用例3代码示例： github.com/BwlSamples/BwlTaggedArtifact 其他代码示例： github.com/BwlSamples/BwlBulkRegistration下载每个代码示例。 学习代码，对其进行编译，然后运行或修改以满足您的需求。 以下各节重点介绍了一些实现细节，并提供了对应用程序输出进行进一步分析的示例。
所有程序都需要三个强制性命令行参数：用户，密码和帐户名。 还有针对每个程序的可选参数。
对于第一个用例，您想从特定的Blueworks Live帐户获取所有附件文档，并将它们下载到本地文件系统。 然后，您只想获取自上次调用以来添加到Blueworks Live存储库中的文件。
BwlFileDownloader程序实现第一个用例。 从“下载”部分，下载用例1代码示例： github.com/BwlSamples/BwlFileDownloader 。 您可以将-f timestamp.txt添加到程序调用中，以移交包含2015-07-01日期的文件，例如2015-07-01 。
然后，该程序使用REST API从该日期开始从您的Blueworks Live帐户获取所有附加文档的列表。 它将每个文件下载到本地目录，您可以使用以下可选的命令行标志指定该目录： -d mydownloaddirectory 。
默认目录是./downloads 。 通过REST API下载文件，并将检索到的二进制数据直接写入相应的文件。 请注意具有相同名称的文档，它们会相互覆盖。
在第一个电话，就可以跳过-f选项，这意味着你不设定任何from日期和您从Blueworks得到所有附件Live帐户直到今天。 该程序还将当前日期写入文件（默认为timestamp.txt）。
在连续的调用中，使用-f timestamp.txt选取上一个下载日期，仅下载该日期之后的文档，然后使用新的日期覆盖timestamp.txt文件。 然后，几天后就可以进行下一个增量下载了。
有关更多信息，请参见代码示例压缩文件中包含的文档。
在第二个用例中，您要确定用户在特定时间段内的最后登录时间。
BwlUserStats程序实现了第二个用例场景。 从“下载”部分，下载用例2代码示例： github.com/BwlSamples/BwlUserStats 。
BwlUserStats程序以与第3部分中使用的示例实现不同的方式实现了第二个用例场景。 这次，您既要请求登录数据，又要请求用户更新的信息。
该程序最多可以创建四个文件，其中包含与LOGINS，COMMENTS，ITEMS_CHANGED和ITEMS_VIEWED相对应的信息。
要获得活动信息类型的完整列表，请参阅第2部分 ，以讨论第二个用例场景。 每种登录或更新类型均以单行逗号分隔值（CSV）文件存储在其中一个输出文件中。 有关更多信息，请参见代码示例压缩文件中包含的文档。
值得考虑的实现细节是周期计算和日期转换：
由于/scr/api/activity REST API资源最多只允许31天，因此该程序在所需的开始日期和结束日期之间创建连续的时间段，并根据需要发送尽可能多的相应调用以覆盖更长的时间段。 为简化起见，该程序采用简单的日期格式（例如2015-07-01 ，并将其转换为API调用所需的更长的ISO8601日期时间格式。 同样，对于日志记录和CSV文件输出，日期将转换为可读性更高的日期时间格式。CSV输出文件可能包含大量数据，并且可以使用Microsoft Excel进行进一步分析。 图1中的屏幕截图显示了ITEMS_CHANGED输出的示例，该输出显示了6个月内用户的更改数量。 有关更多信息，包括有关创建图表的提示，请参阅代码示例压缩文件中包含的文档。
在第三个用例中，您要生成一个报告，列出所有用特定关键字标记的工件，并包含诸如工件类型，名称和ID之类的详细信息。
BwlTaggedArtifacts程序实现了第三个用例场景。 从“下载”部分，下载用例3代码示例： github.com/BwlSamples/BwlTaggedArtifact 。
在第3部分中 ，您发现由于返回的搜索响应的复杂性，很难通过Client for URL（cURL）和shell命令获得所需的输出。 但是，在Java中，由于具有直接访问JSON对象的功能，因此非常简单。
该程序遍历返回的空格列表，并检查所需的标记。 如果为某个空间提供了诸如流程或决策之类的工件，则对这些工件进行相同的操作并打印结果。
查看以下示例命令以获取Windows命令（cmd）Shell和输出。
java -cp .;commons-io-2.4.jar;wink-json4j-1.3.0.jar BwlTaggedArtifacts westphal@de.ibm.com XXX IBM70 demo示例命令返回以下输出：
space,Prozessbearbeitung,400006dea8b3989 space,Mediteran Autoteile,3ea6e050b space,2.3.6 Garantiemanagement,30000d5ea8b30c7 process,Garantieabwicklung,c83e8fdd25 process,Garantieabwicklung mit Regelservice,100003bea79d1aa decision,Gutachtenbedarf ermitteln,8b3fb24eba有关更多信息，请参见代码示例压缩文件中包含的文档。
例如，可以使用Microsoft Excel或第3部分中所示的shell命令来进一步处理结果。 通过在UNIX或Linux Shell中或在Windows上使用Cygwin添加以下管道，可以提取所有空格并按字母顺序对名称进行排序。
以下示例命令使用Cygwin（提供与Linux发行版相似的功能的开源工具的集合）：
java -cp ".;commons-io-2.4.jar;wink-json4j-1.3.0.jar" BwlTaggedArtifacts westphal@de.ibm.com XXX IBM70 demo | grep "^space" | sort示例命令返回以下输出：
space,2.3.6 Garantiemanagement,30000d5ea8b30c7 space,Mediteran Autoteile,3ea6e050b space,Prozessbearbeitung,400006dea8b3989现在，您已经使用IBM Blueworks Live REST API系列完成了“ 做更多事情”的第四部分。 以对API的深入了解以及必要的工具和示例作为起点。 现在，您可以实现自己的工具，以通过Blueworks REST API来提高生产力。
Java方法适用于在一台计算机上运行的独立应用程序，该计算机可以由人手动启动或由自动化（按需或根据预设的时间表）运行。 如果您需要多个用户可以从其浏览器访问的应用程序，就像他们使用Blueworks Live本身一样，那么您需要一种不同的方法。 第5部分介绍了如何设置轻量级的Web服务器以及如何使用Javascript和HTML构建应用程序。
作者要感谢Blueworks Live管理团队的Margaret Thorpe对教程概念的帮助，以及开发团队的Daniel Treiber和技术销售团队的Sean Roe的审阅和评论。
翻译自: https://www.ibm.com/developerworks/bpm/library/techarticles/1603_westphal3-trs/1603_westphal3.html
相关资源：android下live555 rtsp库的移植，及其本地文件推流到rtsp地址demo