如何进入Java SCA软件的开发

该文档是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