该文档是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
2162
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
