该文档是SCA Java项目的开发者指南
l 一般性指南
l 获取源代码
l 配置你的开发环境
l 构建二进制和源代码发布包
l 导入SCA模块到你的开发IDE环境中
l 理解SCA代码路径
l 编码指南
l 测试
l Maven构建结构
l 报告遇到的问题和提供补丁
l 开发提示
Ø 为Webapp样例代码生成Eclipse WTP Web工程
Ø 为样例中的程序生成ant的依赖关系
一般性指南
欢迎来到Tuscany SCA java子工程。我们期待你的参与并努力帮助你。在邮件列表中问你问题是非常轻松的。
这里有些我们这个项目中所使用的一般原则
l Java SCA子项目的目的是为了提供一个基于SCA的企业级的服务基础设施
l Tuscany SCA不仅仅是一个参考的实现。我们鼓励基于SCA原则上的创新。我们所做的许多工作是对规范提供一个反馈。
l Java SCA基础设施应该提供灵活性和可选择性。它不应该规定死编程模型而是应该支持多种编程模型。
l Java SCA基础设施是非常模块化的,高度的可扩展性以便用户可以定制它来适合自己的需求。
获取源代码
Java SCA项目的Subversion 库的地址:https://svn.apache.org/repos/asf/incubator/tuscany/java/sca
也可以在地址:http://svn.apache.org/viewvc/incubator/tuscany/java上在线查看。
任何人都可以check out出代码。你只需要指定用户名和密码以便更新subversion库,当然只有Tuscany提交者才有权限做这些。
从Subversion里check out代码
使用如下的命令:
Svn checkout http://svn.apache.org/repos/asf/incubator/tuscany/java/sca
提交修改到Subversion
任何的Tuscany提交者在svn.apache.org上都应该有一个帐号。在你能提交之前,你需要设置你自己的Subversion的密码。可以登陆到svn.apache.org,然后运行svnpasswd命令。
一旦设置了密码,你就可以用下面的命令提交:
svn commit
如果Subversion没有给出你的用户名,你可以显式地告诉它:
svn –username <name> commit
Subversion会提示你输入密码,一旦你输入后,它将记住密码。注意你用svnpasswd配置的密码不是你的shell或其他的密码。
配置开发环境
首要条件:
Java SCA要求如下:
l JDK 5.0+ (J2SE 1.5.0+)
l Apache Maven(2.0.5)(注意:现在使用Maven的版本高于2.0.5可能会在构建Tuscany时出现问题,查看TUSCANY-1676)
l Subversion(1.2+)
构建树结构
构建树有利于模块化开发和发布。Java SCA当前是使用如下的模块分层:
-java
|-- sca
|-- demos SCA 演示应用程序
|-- distribution SCA 发布程序
|-- itest SCA 集成测试
|-- modules SCA 实现的各个模块 (core, runtimes, contribution, extensions等等)
|-- samples SCA 样例程序
|-- tools SCA 工具 (Eclipse插件, wsdl2java, java2wsdl等等)
|-- tutorial SCA 教程
自顶向下的构建(推荐方法)
Check out出所有的java源代码
svn checkout http://svn.apache.org/repos/afs/incubator/tuscany/java
构建SCA源代码非常简单
cd java/sca
mvn
即使你由一个空的Maven本地库,它也是会工作的。它总是会有效的,但是当你第一次构建Tuscany项目的时候会下载许多依赖的库,这个会花费比较长的时间,当然也有可能在获取依赖库的时候失败。
在从远程的Maven库下载的时候会发生偶然性的问题,所以假如mvn失败是与网络相关的话,只要再重试一遍就可以解决问题了。
主干代码有时候会SNAPSHOT依赖,该依赖从你的本地库获取时间。所以如果你用下列命令升级了SNAPSHOT jar,你会看到odd构建失败信息。
mvn –U
一旦你做了自顶向下的构建,你的本地maven库就组装好了,你能用maven的离线选项加速构建的过程
mvn –o
构建二进制和源代码发布包
二进制和源代码发布包是在distribution文件夹下运行maven命令创建的,如下:
cd java/sca/distribution
mvn clean install –o
发布包工件生成在distribution文件夹下的target文件夹下。
导入SCA模块到你的开发IDE环境中
使用Eclipse
假如这是你第一次用maven m2本地库用于你的workspace(Eclipse里的工作空间),你要告知你的Eclipse工作空间的目录路径,命令如下:
mvn –Declipse.workspace=[path-to-eclipse-workspace] eclipse:add-maven-repo
为了生成必要的项目文件,你需要使用maven的eclipse插件
cd java/sca
mvn –Peclipse eclipse:eclipse
现在,启动你的Eclipse IDE,选择FileàImportàExisting projects into Workplace,然后选择SCA的启始目录(例如 java/sca),然后按Finish,就会导入所有的SCA模块到Eclipse中了。
理解SCA的代码路线
这里有一个关键方法/函数的概述可以帮助你入门SCA java开发。
(请看我翻译的SCA编码入门)
编码指南
开发java SCA有些简单的指导原则:
l 基本的编码风格在Sun Java编码标准里描述了,但主要是要保证与你正在升级的代码保持一致性。
l 总是在所有的文件包含Apache License的头信息(源代码和象xml文档的资源文件都包含)
l 包含checkin信息的描述日子信息,比如“修复了某某某问题”
命名规范增强代码一致性
文件夹名称:都使用小写和-破折号
n Maven的工件id = Tuscany-<文件夹的名字>
包名:模块中的包名应该包含模块名,以便很容易地在代码树上定位源代码。例如,java/sca/module/implementation-java就在包org.apache.tuscany.implementation.java.*里。
测试
Tuscany使用普通的junit测试用例来做单元和集成测试,下面就是一个例子,它可以作为写新的测试用例的一个模板来使用。它演示了在你的测试用例中如何加载Tuscany SCA运行时,同时因为他们是基于junit的,你能选择从IDE或者从Maven启动。
/**
* Description of your test case and necessary details you find necessary
*/
public class YourTestCase extends TestCase {
private SCADomain domain;
private YourService service;
@Override
protected void setUp() throws Exception {
domain = SCADomain.newInstance("YourTest.composite");
service = domain.getService(YourService.class, "serviceName");
}
@Override
protected void tearDown() throws Exception {
domain.close();
}
...
}
注意:我们使用相应的maven插件来运行单元和集成测试,大多数情况,他们都会被配置成匹配**/*TestCase.java文件名模式。因此,假如你的测试用例用了不同的文件名模式,你也许要从你的IDE来执行,而不能用maven来执行该测试。
Maven构建结构
我们使用术语Module(模块)来表示maven树的叶子
l Sca/pom.xml的父文件是pom/parent/pom.xml
l 其他的pom会把父文件夹的pom作为父pom使用
l 组id: oracle.apache.tuscany.sca
l 我们模块的版本在java/sca/pom.xml一次性指定,子pom不需要指定因为他们直接从父pom继承。
l Pom命名开始Apache Tuscany SCA
l 使用mvn –Peclipse:eclipse为所有的构建模块产生Eclipse项目
如何增加新的模块但不准备集成?
‘work-in progress’这个模块工作在同一个代码树上,并没有破坏自定向下的构建。你能通过不在java/sca/modules/pom.xml文件中不列出你的模块做到这点。
报告遇到的问题并提供补丁
问题跟踪
Tuscany bug报告是通过JIRA问题列表来处理的。请用这个列表来报告bug和追踪他们的状态。
报告问题
请搜索JIRA查看下是否这个问题已经报告了。假如没有,请创建新的JIRA问题。为了帮助开发者快速解决问题,请尽可能地包含更多的信息,比如你的平台、版本号、错误log、配置,再现问题的步骤等等。如果可能,请包含演示代码的测试用例。
感谢和我们一道完善Apache Tuscany。
提交补丁程序
为了提交补丁,在JIRA中创建一个描述问题的布告,并附上你的补丁文件。请包含如何再现问题的详细步骤,在补丁中提供测试用例可以帮助更快地验证和应用该补丁。要创建补丁,遵从如下步骤:
l 执行所有的修正模块的测试。具体的构建过程以子工程不同而不同。
l 确认修订的问题,尽可能包含测试用例。
l 用svn diff File > patchfile命令产生补丁。
l 给出你的补丁文件的全名,包括JIRA number。
l 在相关的JIRA 公告上以附件的方式附加上你的补丁文件。
Ø 单击屏幕中的’Patch Avaliable’框,补丁将提交到这里,这样做能帮助快速地标识有效的补丁程序。
一旦你提交了补丁,就可以在review里看到。谢谢
开发提示
为Webapp样例代码产生Eclipse WTP Web工程
如果你正在使用Eclipse WTP并想为我们的Webapp样例程序产生Web工程,你能简单地传一个-Dwtpversion=1.5的选项给通常的mvn eclipse:eclipse命令,如下:
mvn –Dwtpversion=1.5 –Peclipse eclipse:eclipse
这个-Dwtpversion=1.5的选项会增加WTP web工程的属性到在Maven 的pom.xml文件中标有<packaging>war</packaging>的所有的eclipse工程。你能添加这些工程到Tomcat或Geronimo(Apache Geronimo 是一个大型的开放源码项目)服务器配置中,发布并从你的Eclipse工作空间中运行。
为样例中的程序生成ant的依赖关系
在Ant 的build.xml文件中指定库的依赖关系是十分痛苦的。这里有一个运行与Linux环境中快速脚本。
jar tvf sample-feed-aggregator-webapp.war | grep .jar | awk '{ printf "%s\n", $8 }' | sed -e "s/WEB-INF\/lib\///" | awk '{ printf "<include name=\"%s\"/>\n", $1 }' | grep -v tuscany
l 一般性指南
l 获取源代码
l 配置你的开发环境
l 构建二进制和源代码发布包
l 导入SCA模块到你的开发IDE环境中
l 理解SCA代码路径
l 编码指南
l 测试
l Maven构建结构
l 报告遇到的问题和提供补丁
l 开发提示
Ø 为Webapp样例代码生成Eclipse WTP Web工程
Ø 为样例中的程序生成ant的依赖关系
一般性指南
欢迎来到Tuscany SCA java子工程。我们期待你的参与并努力帮助你。在邮件列表中问你问题是非常轻松的。
这里有些我们这个项目中所使用的一般原则
l Java SCA子项目的目的是为了提供一个基于SCA的企业级的服务基础设施
l Tuscany SCA不仅仅是一个参考的实现。我们鼓励基于SCA原则上的创新。我们所做的许多工作是对规范提供一个反馈。
l Java SCA基础设施应该提供灵活性和可选择性。它不应该规定死编程模型而是应该支持多种编程模型。
l Java SCA基础设施是非常模块化的,高度的可扩展性以便用户可以定制它来适合自己的需求。
获取源代码
Java SCA项目的Subversion 库的地址:https://svn.apache.org/repos/asf/incubator/tuscany/java/sca
也可以在地址:http://svn.apache.org/viewvc/incubator/tuscany/java上在线查看。
任何人都可以check out出代码。你只需要指定用户名和密码以便更新subversion库,当然只有Tuscany提交者才有权限做这些。
从Subversion里check out代码
使用如下的命令:
Svn checkout http://svn.apache.org/repos/asf/incubator/tuscany/java/sca
提交修改到Subversion
任何的Tuscany提交者在svn.apache.org上都应该有一个帐号。在你能提交之前,你需要设置你自己的Subversion的密码。可以登陆到svn.apache.org,然后运行svnpasswd命令。
一旦设置了密码,你就可以用下面的命令提交:
svn commit
如果Subversion没有给出你的用户名,你可以显式地告诉它:
svn –username <name> commit
Subversion会提示你输入密码,一旦你输入后,它将记住密码。注意你用svnpasswd配置的密码不是你的shell或其他的密码。
配置开发环境
首要条件:
Java SCA要求如下:
l JDK 5.0+ (J2SE 1.5.0+)
l Apache Maven(2.0.5)(注意:现在使用Maven的版本高于2.0.5可能会在构建Tuscany时出现问题,查看TUSCANY-1676)
l Subversion(1.2+)
构建树结构
构建树有利于模块化开发和发布。Java SCA当前是使用如下的模块分层:
-java
|-- sca
|-- demos SCA 演示应用程序
|-- distribution SCA 发布程序
|-- itest SCA 集成测试
|-- modules SCA 实现的各个模块 (core, runtimes, contribution, extensions等等)
|-- samples SCA 样例程序
|-- tools SCA 工具 (Eclipse插件, wsdl2java, java2wsdl等等)
|-- tutorial SCA 教程
自顶向下的构建(推荐方法)
Check out出所有的java源代码
svn checkout http://svn.apache.org/repos/afs/incubator/tuscany/java
构建SCA源代码非常简单
cd java/sca
mvn
即使你由一个空的Maven本地库,它也是会工作的。它总是会有效的,但是当你第一次构建Tuscany项目的时候会下载许多依赖的库,这个会花费比较长的时间,当然也有可能在获取依赖库的时候失败。
在从远程的Maven库下载的时候会发生偶然性的问题,所以假如mvn失败是与网络相关的话,只要再重试一遍就可以解决问题了。
主干代码有时候会SNAPSHOT依赖,该依赖从你的本地库获取时间。所以如果你用下列命令升级了SNAPSHOT jar,你会看到odd构建失败信息。
mvn –U
一旦你做了自顶向下的构建,你的本地maven库就组装好了,你能用maven的离线选项加速构建的过程
mvn –o
构建二进制和源代码发布包
二进制和源代码发布包是在distribution文件夹下运行maven命令创建的,如下:
cd java/sca/distribution
mvn clean install –o
发布包工件生成在distribution文件夹下的target文件夹下。
导入SCA模块到你的开发IDE环境中
使用Eclipse
假如这是你第一次用maven m2本地库用于你的workspace(Eclipse里的工作空间),你要告知你的Eclipse工作空间的目录路径,命令如下:
mvn –Declipse.workspace=[path-to-eclipse-workspace] eclipse:add-maven-repo
为了生成必要的项目文件,你需要使用maven的eclipse插件
cd java/sca
mvn –Peclipse eclipse:eclipse
现在,启动你的Eclipse IDE,选择FileàImportàExisting projects into Workplace,然后选择SCA的启始目录(例如 java/sca),然后按Finish,就会导入所有的SCA模块到Eclipse中了。
理解SCA的代码路线
这里有一个关键方法/函数的概述可以帮助你入门SCA java开发。
(请看我翻译的SCA编码入门)
编码指南
开发java SCA有些简单的指导原则:
l 基本的编码风格在Sun Java编码标准里描述了,但主要是要保证与你正在升级的代码保持一致性。
l 总是在所有的文件包含Apache License的头信息(源代码和象xml文档的资源文件都包含)
l 包含checkin信息的描述日子信息,比如“修复了某某某问题”
命名规范增强代码一致性
文件夹名称:都使用小写和-破折号
n Maven的工件id = Tuscany-<文件夹的名字>
包名:模块中的包名应该包含模块名,以便很容易地在代码树上定位源代码。例如,java/sca/module/implementation-java就在包org.apache.tuscany.implementation.java.*里。
测试
Tuscany使用普通的junit测试用例来做单元和集成测试,下面就是一个例子,它可以作为写新的测试用例的一个模板来使用。它演示了在你的测试用例中如何加载Tuscany SCA运行时,同时因为他们是基于junit的,你能选择从IDE或者从Maven启动。
/**
* Description of your test case and necessary details you find necessary
*/
public class YourTestCase extends TestCase {
private SCADomain domain;
private YourService service;
@Override
protected void setUp() throws Exception {
domain = SCADomain.newInstance("YourTest.composite");
service = domain.getService(YourService.class, "serviceName");
}
@Override
protected void tearDown() throws Exception {
domain.close();
}
...
}
注意:我们使用相应的maven插件来运行单元和集成测试,大多数情况,他们都会被配置成匹配**/*TestCase.java文件名模式。因此,假如你的测试用例用了不同的文件名模式,你也许要从你的IDE来执行,而不能用maven来执行该测试。
Maven构建结构
我们使用术语Module(模块)来表示maven树的叶子
l Sca/pom.xml的父文件是pom/parent/pom.xml
l 其他的pom会把父文件夹的pom作为父pom使用
l 组id: oracle.apache.tuscany.sca
l 我们模块的版本在java/sca/pom.xml一次性指定,子pom不需要指定因为他们直接从父pom继承。
l Pom命名开始Apache Tuscany SCA
l 使用mvn –Peclipse:eclipse为所有的构建模块产生Eclipse项目
如何增加新的模块但不准备集成?
‘work-in progress’这个模块工作在同一个代码树上,并没有破坏自定向下的构建。你能通过不在java/sca/modules/pom.xml文件中不列出你的模块做到这点。
报告遇到的问题并提供补丁
问题跟踪
Tuscany bug报告是通过JIRA问题列表来处理的。请用这个列表来报告bug和追踪他们的状态。
报告问题
请搜索JIRA查看下是否这个问题已经报告了。假如没有,请创建新的JIRA问题。为了帮助开发者快速解决问题,请尽可能地包含更多的信息,比如你的平台、版本号、错误log、配置,再现问题的步骤等等。如果可能,请包含演示代码的测试用例。
感谢和我们一道完善Apache Tuscany。
提交补丁程序
为了提交补丁,在JIRA中创建一个描述问题的布告,并附上你的补丁文件。请包含如何再现问题的详细步骤,在补丁中提供测试用例可以帮助更快地验证和应用该补丁。要创建补丁,遵从如下步骤:
l 执行所有的修正模块的测试。具体的构建过程以子工程不同而不同。
l 确认修订的问题,尽可能包含测试用例。
l 用svn diff File > patchfile命令产生补丁。
l 给出你的补丁文件的全名,包括JIRA number。
l 在相关的JIRA 公告上以附件的方式附加上你的补丁文件。
Ø 单击屏幕中的’Patch Avaliable’框,补丁将提交到这里,这样做能帮助快速地标识有效的补丁程序。
一旦你提交了补丁,就可以在review里看到。谢谢
开发提示
为Webapp样例代码产生Eclipse WTP Web工程
如果你正在使用Eclipse WTP并想为我们的Webapp样例程序产生Web工程,你能简单地传一个-Dwtpversion=1.5的选项给通常的mvn eclipse:eclipse命令,如下:
mvn –Dwtpversion=1.5 –Peclipse eclipse:eclipse
这个-Dwtpversion=1.5的选项会增加WTP web工程的属性到在Maven 的pom.xml文件中标有<packaging>war</packaging>的所有的eclipse工程。你能添加这些工程到Tomcat或Geronimo(Apache Geronimo 是一个大型的开放源码项目)服务器配置中,发布并从你的Eclipse工作空间中运行。
为样例中的程序生成ant的依赖关系
在Ant 的build.xml文件中指定库的依赖关系是十分痛苦的。这里有一个运行与Linux环境中快速脚本。
jar tvf sample-feed-aggregator-webapp.war | grep .jar | awk '{ printf "%s\n", $8 }' | sed -e "s/WEB-INF\/lib\///" | awk '{ printf "<include name=\"%s\"/>\n", $1 }' | grep -v tuscany