包结构也要精心设计

冰浪 — Thu, 26 Jul 2007 12:46:00 GMT

摘要: 我们不要简单地按功能模块的方式来设计包，要考虑到模块间的逻辑关系，让有关系的模块的包设计成“父子包”的形式，而不是按功能模块简单地设计成平行结构，这不利于类之间的交互。阅读全文

冰浪 2007-07-26 20:46 发表评论

[转]利用反射动态调用类成员

冰浪 — Wed, 11 Jul 2007 12:32:00 GMT

摘要: 使用反射来调用类的方法，需要使用java.lang.reflect.Method中的invoke方法，Object??invoke(Object obj, Object[] args)，第一个参数是指需要调用的那个方法的隐式参数，也即那个方法所属的对象，如果调用的是一个静态方法将第一个参数指定为null，第二个参数是指需要调用的那个方法的显式参数，因为一个方法可以有很多个参数所以在这里我们必须用一个数组来存放这些参数，注意这个方法使用的是对象数组，在存放时尽管有值类型我们也要把相应的包装器类存放进去，当调用的这个方法有返回值，这在Java中是一个令人烦恼的问题，如果返回来的是一个对象还好，我们只需将invoke返回的Object强制转换成特定的对象就可以，可是返回一个值类型呢？我们要使用就麻烦了，首先要对其解包装，在用其包装对象的方法返回普通值！我们编程思路很重要是吧阅读全文

冰浪 2007-07-11 20:32 发表评论

详细解析Java中抽象类和接口的区别(来自：java060515)

冰浪 — Sun, 13 May 2007 10:41:00 GMT

摘要: 在Java语言中， abstract class 和interface 是支持抽象类定义的两种机制。正是由于这两种机制的存在，才赋予了Java强大的面向对象能力。abstract class和interface之间在对于抽象类定义的支持方面具有很大的相似性，甚至可以相互替换，因此很多开发者在进行抽象类定义时对于abstract class和interface的选择显得比较随意。其实，两者之间还是有很大的区别的，对于它们的选择甚至反映出对于问题领域本质的理解、对于设计意图的理解是否正确、合理。本文将对它们之间的区别进行一番剖析，试图给开发者提供一个在二者之间进行选择的依据。阅读全文

冰浪 2007-05-13 18:41 发表评论

[原]java语言中方法覆盖的一点思考

冰浪 — Fri, 16 Feb 2007 12:15:00 GMT

摘要: 在java的继承中，我们可以在子类中定义一方法去覆盖父类中定义的同名同参方法，这叫方法覆盖。其中有一点让我几经思考：父类的私有方法不能被子类覆盖。
阅读全文

冰浪 2007-02-16 20:15 发表评论

Javadoc的简捷使用

冰浪 — Thu, 18 Jan 2007 03:24:00 GMT

J2SE5中的javadoc.exe的命令行可选参数多达五十余个，其复杂性可想而知，是不是看着头都大了呢？但通常情况下，我们不想那么麻烦！

假设源代码在 C:\src 目录下，其中 com.liigo 是主包，其下可能有数十个子包，数百（千）个Java文件。目录结构大约是这样的：

- C:\
    | src\
      | com\
        | liigo\

| ***

怎么才能以最简捷的方式生成所有的API文档呢？

c:\>
c:\>cd src
c:\src>javadoc -d doc -subpackages com.liigo

这样就搞定了，最终生成的API文档位于 c:\src\doc 目录（该目录是由javadoc.exe自动生成的）。

上面的用法利用了“当前目录”和“相对路径”，当然也可以用绝对路径：

...>javadoc -d c:\doc -sourcepath c:\src -subpackages com.liigo

最终生成的API文档位于 c:\doc 目录（该目录同样是由javadoc.exe自动生成的）。

总结一下：

我们只用到了javadoc的三个参数： -d，-subpackages，-sourcepath，其中：

参数说明
-d 指定API文档的输出目录，默认是当前目录。建议总是指定该参数。
-sourcepath 指定源代码路径，默认是当前目录。此参数通常是必须的。
-subpackages 以递归的方式处理各子包。关键参数！如果不使用本参数，每次只能处理一个子包（或需手工列出所有子包）。

注：以上示例要求 javadoc.exe 所在路径位于系统环境变量“PATH”中。

补充一点：

使用参数 -author 可以将作者信息（@author ***）导出到最终生成的API文档中， -version 可以生成版本信息。如果是自己写的一个包，千万不要忘了用 -author 哦:)

最终完整的命令行是：

...>javadoc -d c:\doc -sourcepath c:\src -subpackages com.liigo -author -version

javadoc的命令行语法如下：

javadoc [ options ] [ packagenames ] [ sourcefiles ] [ @files ]

参数可以按照任意顺序排列。下面分别就这些参数和相关的一些内容进行说明：

Packagenames 包列表。这个选项可以是一系列的包名（用空格隔开），例如java.lang java.lang.reflect
java.awt。不过，因为javadoc不递归作用于子包，不允许对包名使用通配符；所以你必须显示地列出希望建立文档的每一个包。
Sourcefiles 源文件列表。这个选项可以是一系列的源文件名（用空格隔开），可以使用通配符。javadoc允许四种源文件：类源代码文件、包描述文件、总体概述文件、其他杂文件。

◇ 类源代码文件：类或者接口的源代码文件。

◇ 包描述文件：每一个包都可以有自己的包描述文件。包描述文件的名称必须是"package.html"，与包的.java文件放置在一起。包描述文件的内容通常是使用HTML标记写的文档。javadoc执行时将自动寻找包描述文件。如果找到，javadoc将首先对描述文件中之间的内容进行处理，然后把处理结果放到该包的Package
Summary页面中，最后把包描述文件的第一句（紧靠）放到输出的Overview summary页面中，并在语句前面加上该包的包名。

◇ 总体概述文件：javadoc可以创建一个总体概述文件描述整个应用或者所有包。总体概述文件可以被任意命名，也可以放置到任意位置。-overview选项可以指示总体概述文件的路径和名称。总体概述文件的内容是使用HTML标记写的文档。javadoc在执行的时候，如果发现-overview选项，那么它将首先对文件中之间的内容进行处理；然后把处理后的结果放到输出的Overview
summary 页面的底部；最后把总体概述文件中的第一句放到输出的Overview summary页面的顶部。

◇ 其他杂文件：这些文件通常是指与javadoc输出的HTML文件相关的一些图片文件、Java源代码文件（.java）、Java程序（.class）、Java小程序（Applets）、HTML文件。这些文件必须放在doc-files目录中。每一个包都可以有自己的doc-files目录。举个例子，你希望在java.awt.Button的HTML文档中使用一幅按钮的图片（Button.gif）。首先，你必须把图片文件放到C:\user\src\java\awt\doc-files\中；然后在Button.java文件中加入下面注释

/**

* This button looks like this:

*

*/
@files 包含文件。为了简化javadoc命令，你可以把需要建立文档的文件名和包名放在一个或多个文本文件中。例如，为了简化下面命令：

javadoc -d apidoc com.mypackage1 com.mypackage2 com.mypackage3

你可以建立一个名称为mypackage.txt的文件，其内容如下：

com.mypackage1

com.mypackage2

com.mypackage3

然后执行下面命令即可：

javadoc -d apidoc @mypackage.txt
options 命令行选项。javadoc使用doclets（doclets是指用doclet API编写的程序。）来确定输出的内容和格式。命令行选项中一部分是可用于所有doclet的通用选项，一部分是由默认的标准doclet提供的专用的选项。下面对各自一些常用的选项分别进行介绍：

通用选项：

◇ -1.1 生成具有javadoc 1.1版本生成的文档的外观和功能的文档。不是所有的选项都可以用于-1.1选项，具体可以使用javadoc
-1.1 -help察看。

◇ -help 显示联机帮助。

◇ -bootclasspath classpathlist 指定"根类"（通常是Java平台自带的一些类。例如java.awt.*等）的路径。

◇ -sourcepath sourcepathlist 指定包的源文件搜索路径。但是必须注意，只有在javadoc命令中指定了包名的时候才可以使用-sourcepath选项。如果指定了包名，而省略了-sourcepath，那么javadoc使用类路径查找源文件。举例说明：假定你打算为com.mypackage建立文档，其源文件的位置是C:\user\src。那么你可以使用下面的命令：

javadoc -sourcepath c:\user\src com.mypackage

◇ -classpath classpathlist 指定javadoc查找"引用类"的路径。引用类是指带文档的类加上它们引用的任何类。javadoc将搜索指定路径的所有子目录。Classpathlist可以包含多个路径（使用;隔开）。如果省略-classpath，则javadoc使用-sourcepath查找源文件和类文件。举例说明：假定你打算为com.mypackage建立文档，其源文件的位置是C:\user\src，包依赖C:\user\lib中的库。那么你可以使用下面的命令：

javadoc -classpath c:\user\lib -sourcepath c:\user\src com.mypackage

◇ -overview path\filename 告诉javadoc从path\filename所指定的文件中获取概述文档，并且把它放到输出的概述页面（overview-summary.html）中。其中path\filename是相对于-sourcepath的相对路径。

◇ -public 只显示公共类以及成员。

◇ -protected 只显示受保护的和公共的类以及成员。缺省选项。

◇ -package只显示包、受保护的和公共的类以及成员。

◇ -private 显示所有类和成员。

◇ -doclet class 指定javadoc产生输出内容的自定义doclet类。如果忽略这个选项，javadoc将使用默认的doclet产生一系列HTML文档。

◇ -docletpath classpathlist 与- doclet选项相关，制定自定义的doclet类文件的路径。Classpathlist可以包含多条路径（用;隔开）。

◇ -verbose 在javadoc运行时提供更详细的信息。

标准doclet专用选项：

◇ -author 在生成的文档中包含"作者"项。

◇ - d directory 指定javadoc保存生成的HTML文件的目录。省略该选项将把文件保存在当前目录。Directory可以是绝对目录，也可以是相对当前目录的相对目录。

◇ -version 在生成的文档中包含"版本"项。

◇ -use 为类和包生成"use"（用法）页面。这些页面描述了该类和包在javadoc命令涉及的文件中被使用的情况。例如：对于给定的类C，在C的用法页面中将包含C的子类，类型为C的域，返回变量类型为C的方法以及在参数中有变量类型为C的方法和构造器。

◇ -splitindex 把索引文件按照字母顺序分为多个文件。每一个文件对应一个字母。

◇ -windowtitle title 指定输出的HTML文档的标题。

◇ -header header 指定输出的HTML文档的页眉文本。

◇ -footer footer 指定输出的HTML文档的脚注文本。

◇ -bottom text 指定输出的HTML文档底部的文本。

◇ - group groupheading packagepatten;packagepatten;… 在总体概述页面中按照命令的指定方式分隔各个包。例如执行下面命令：

javadoc -group "Core Packages" "java.lang*:java.util"

-group "Extension Packages" "javax.*"

java.lang java.lang.reflect java.util javax.servlet java.new

在页面中将有如下结果：

Core Packages

java.lang

java.lang.reflect

java.util

Extension Packages

javax.servlet

Other Packages

java.new

◇ - noindex 不输出索引文件。

◇ - help 在文件的导航条中忽略help链接。

◇ - helpfile path\filename 指定导航条中的help链接所指向的帮助文件。忽略该选项，javadoc将生成缺省的帮助文件。

◇ -stylesheetfile path\filename 指定javadoc的HTML样式表文件的路径。忽略该选项，javadoc将自动产生一个样式表文件stylesheet.css。

通过上面的介绍，我们了解了javadoc的命令行语法，下面开始介绍javadoc文档注释方法。

javadoc注释以"/**"开始，以"*/"结束，里面可以包含普通文本、HTML标记和javadoc标记。javadoc只处理源文件中在类/接口定义、方法、域、构造器之前的注释，忽略位于其他地方的注释。举例如下：
/**

*我的第一个程序--Helloworld

*@author 王鸿

*@version 1.0 2001/10/15

*/

public class myHelloworld

{

/**

*在main( )方法中使用的显示用字符串

*@see #main(java.lang.String[])

*/

static String SDisp

使用下面命令：

javadoc -private -d doc -author -version myHelloworld.java

即可以生成漂亮的关于myHelloworld.java的API文档了。

上面例子中以@开头的标记就是javadoc标记。在Java程序中正确使用javadoc标记是一个良好的注释习惯，将非常有助于javadoc自动从源代码文件生成完整的格式化API文档。下面就对各种标记进行详细说明。

◇ @author name-text 指定生成文档中的"作者"项，从JDK/SDK 1.0开始引入。name-text可以指定多个名字（使用","隔开）。文档注释可以包含多个类。

◇ {@docroot} 代表产生文档的根路径，从JDK/SDK 1.3开始引入。用法举例如下

/**

*see the copyright

*/

假定生成文档的根目录是doc，上面注释所在的文件最后生成的文件是doc\utility\utl.html，那么"copyright"的链接会指向..\copyright.html。

◇ @deprecated deprecated-text 添加注释，表明不推荐使用该API。

◇ @exception class-name description @throw的同义标记，从JDK/SDK 1.0开始引入。

◇ {@link package.class#member label} 插入指向package.class#member的内嵌链接，从JDK/SDK
1.2开始引入。举例说明，假定注释中有如下文档：

/** Use the {@link #getComponentAt(int, int) getComponentAt} method. */

那么javadoc最终生成的HTML页面中将有如下内容

Use the > getComponentAt method.

◇ @param parameter-name description 描述参数，从JDK/SDK 1.0开始引入。

◇ @return description 描述返回值，从JDK/SDK 1.0开始引入。

◇ @see reference 添加"参见"标题，其中有指向reference的链接或者文本项，从JDK/SDK
1.0开始引入。@see标记有三种形式，下面分别说明：

（1）、@see "string" 为"string"添加文本项，不产生链接。

（2）、@see Label 使用HTML标记产生链接

（3）、@see package.class#member Label 使用Java语言的名字package.class #member产生链接。

◇ @serial field-description 用于缺省可序列化域的注释，从JDK/SDK 1.2开始引入。

◇ @serialField field-name field-type field-description 建立Serializable类的serialPersistentFields成员的ObjectStreamField组件的文档，从JDK/SDK
1.2开始引入。

◇ @serialData data-description data-description建立数据序列和类型的文档，从JDK/SDK
1.2开始引入。

◇ @since since-text 利用since-text内容为文档增加"since"标题，从JDK/SDK
1.1开始引入。

◇ @throws class-name description 与@exception同义。用class-name和description为输出文档添加"抛出"标题，从JDK/SDK
1.2开始引入。

◇ @version version-text 添加"版权"标题，从JDK/SDK 1.0开始引入。

上面介绍了标准doclet提供的所有标记。不过，需要注意这些标记的使用是有位置限制的。其中可以出现在类或者接口文档注释中的标记有：@see、{@link}、@since、@deprecated、@author、@version。可以出现在方法或者构造器文档注释中的标记有：@see、{@link}、@since、@deprecated、@param、@return、@throws、@exception、@serialData。可以出现在域文档注释中的有：@see、{@link}、@since、@desprecated、@serial、@serialField。

除了javadoc自身提供的标准标记以外，我们可以定制自己的标记吗？当然可以。只需要对javadoc标准的doclet程序进行扩充即可。实际上，利用javadoc提供的doclet
API，不仅可以扩充doclet标记，甚至还可以改变javadoc的整个输出。为了满足需要，你可以使javadoc输出普通文本、XML文件等。由于扩充doclet涉及到Java编程，本文不再做深入介绍。

总之，javadoc提供了完整规范的API文档功能。在软件项目管理中，合理地使用javadoc不仅可以减少开发时的文档工作量，提高效率；而且还非常有利于将来软件的修改和维护。

冰浪 2007-01-18 11:24 发表评论

BlogJava-冰浪-随笔分类-Java

包结构也要精心设计

[转]利用反射动态调用类成员

详细解析Java中抽象类和接口的区别(来自：java060515)

[原]java语言中方法覆盖的一点思考

Javadoc的简捷使用