创建组件库的过程涉及创建各种不同的部分，然后将这些部分包装到单个 complib 文件中。complib 可以包含以下部分：

• 运行时 JAR 文件，包含在运行时作为应用程序的一部分部署到服务器上的类和元数据。在设计时也会使用运行时 JAR 文件。
• 设计时 JAR 文件，包含 IDE 本身使用的类和元数据，在运行时不会部署这些类和元数据。
• Javadoc zip 文件，包含 IDE 用户的 Javadoc。不会部署这些文件。
• 源文件，包含 IDE 用户使用的 Java 源代码。不会部署这些文件。
• 帮助信息，供 IDE 用户使用（IDE 中尚未实现对 complib 中的这些帮助文件的支持）。

名为 MANIFEST.MF 的 JAR 清单文件指向第二个文件（即配置 XML 文件），而后者又为组件库内容编制目录（第二个目录文件允许使用分层元素和进行国际化）。此示例包含清单文件 META-INF/MANIFEST.MF 和 XML 目录文件 complib-config.xml。IDE 读取这两个文件，但第二个文件 complib-config.xml 包含 complib 的所有相关信息，该文件实际上用作 complib 目录。IDE 可通过该 XML 文件来确定组件库中包含的项（及其类型）。

注意：具有两个文件（MANIFEST.MF 和目录 XML 文件）反映了组件库的当前方法。较早的 complib 可能仅包含 MANIFEST.MF 文件；IDE 将支持这些较早的 complib 以保持向后兼容性。

在详细介绍组件库的各个部分之前，我们先简要介绍一下组件本身。虽然所有 Java Studio Creator 组件未必是 JavaServer Faces 组件，但它们必须是 Bean（例如，数据提供器是 Bean，但不是 JavaServer Faces 组件）。

如果组件是 JavaServer Faces 组件，则它是 UIComponent 的子类。此类组件通常称为可视组件，因为它通常包含用于呈现在用户代理或用户浏览器中显示的标记的代码。对于可视组件，IDE 在设计时在可视设计器中显示呈现的标记。相反，其他类型的 Bean（包括非 JavaServer Faces 组件）称为非可视组件。

运行时工件通常包装在一个或多个 JAR 文件中。样例包含 JavaServer Faces 转换器，它是非可视组件。非可视组件通常是手动实现的。可视组件通常更为复杂。编写 JavaServer Faces 可视组件的过程涉及创建几个 Java 类以及一些元数据：

• 元数据：sample-simple.tld（标记库描述符）和 XML 配置文件
• UIComponent 本身：DatePicker.java 和 PopupCalendar.java
• 组件的呈现器：DatePickerRenderer.java 和 PopupCalendarRenderer.java
• 组件的标记处理程序：DatePickerTag.java 和 PopupCalendarTag.java

虽然这可能看起来需要很大的工作量，但可视组件的大多数信息是样板，甚至可以从一组相同的元数据中派生。一种方法是保留一组元数据并提供代码生成器来派生样板类和配置文件，而不是手动将组件的不同部分保持同步。本文中介绍了这种方法。样例包含两个配置文件（faces-config.xml 和 sun-faces-config.xml），它们包含用作代码生成器输入以生成运行时和设计时工件的元数据。

代码生成器是可选的。如果您在为自己的组件运行代码生成器时出现问题，可通过检查生成器为样例组件生成的输出来确定如何手动编写您自己的代码。

设计时工件通常包装在设计时 JAR 文件中。这些工件包括：

• 设计时类：
• PopupCalendarBeanInfo.java 描述 PopupCalendar Bean。
• PopupCalendarDesignInfo.java 支持动态设计时行为。
• SqlUtilDateConverterBeanInfo.java 描述 SqlUtilDateConverter Bean。
• 其他代码（如定制属性编辑器）：YearAlignPropertyEditor.java
• 其他资源：DatePicker 的 PNG 图标（图像文件）

其他可选文件（如 Javadoc 和源代码文件）也可以包装在 zip 文件中。在开发过程中，IDE 可通过这些文件来提供 Javadoc 和源代码。

complib 包含日期选取器组件、组合的 java.sql.Date 和 java.util.Date 转换器以及某些设计时类。

让我们先创建一个运行时 JAR 文件，它包含日期选取器组件的 JavaServer Faces 组件。您可以手动将 java.util.Date 转换器作为没有任何属性的 Bean 来实现。

可视组件需要三种运行时类：UIComponent 类本身、标记处理程序类以及呈现器。大多数 UIComponent 代码是样板，您可以自动生成这些代码。同样，标记处理程序遵循样板模式，您也可以自动生成该标记处理程序。标记处理程序中不应该包含任何特殊组件代码，因为 Java Studio Creator 2 IDE 在设计时不执行标记处理程序。在这三种类中，呈现器为组件提供其固有特性，因而通常是手动编写的。

您也可以自动生成标记库描述符 TLD 文件。

JavaServer Faces 运行时需要使用配置文件 faces-config.xml 来确定应用程序组件、转换器、验证器和呈现器的类型。但是，faces-config.xml 文件模式是可扩展的，并且 Java Studio Creator 2 可对其进行扩展以允许使用额外的元数据，这些元数据可用作代码生成器输入。通常，该扩展的元数据文件名为 sun-faces-config.xml。

由于在运行时需要使用 faces-config.xml 文件，因此，该文件中仅包含运行时所需的最低限度的元数据。所有扩展的元数据信息都保存在 sun-faces-config.xml 配置文件中。

让我们看一下样例 faces-config.xml 文件。它包含最低限度的日期选取器组件及其呈现器相关信息。创建新的组件时，请先在该文件中添加一些条目。

接下来，查看 sun-faces-config.xml 文件。该文件包含组件的 description、tag-name、taglib-uri、base-component-type 和 instance-name 及其所有属性。每个属性包含描述和其他元数据，如显示名称、类型、JavaBeans 属性编辑器以及属性检查器中的类别。

sun-faces-config.xml 文件中的元数据用于生成以下内容：

• 组件基类，包含具体的属性和值绑定。例如，DatePickerBase.java。
• 标记库处理程序类，包含用于收集 JavaServer Pages (JSP) 属性和在组件类中的属性上设置其值的代码。例如，DatePickerTag.java。
• 标记库描述符文件，通知容器中的 JSP 编译器如何处理 JSP 页面中的标记。例如，sample-simple.tld。
• JavaBeans BeanInfo 基类，包含组件的元数据。例如，DatePickerBeanInfoBase.java。

有关使用 sun-faces-config.xml 文件作为输入来运行 Java Studio Creator 代码生成器的详细信息，请参见 ant build.xml 文件中的 gen-all 目标（build.xml 文件是可下载的样例源代码分发的一部分。您应该打开该文件以查看此目标引用）。但要切记，代码生成器接口可能会发生更改。

运行代码生成器后，您需要手动编写实际的呈现器和组件类。有关详细信息，请参见以下文件中的代码：

• 呈现器类：DatePickerRenderer.java
• 组件类：DatePicker.java，它扩展了 DatePickerBase

最后，收集所有运行时类、资源以及 faces-config.xml 文件并创建运行时 JAR。请参见 ant build.xml 文件中的 jar-rt ant 目标。

下一个主要步骤是创建设计时 JAR 文件。设计时 JAR 文件包含 BeanInfo 类和其他项，它们没有部署到容器上，而仅由某个工具使用。

ant build.xml 文件（由 gen-all 目标运行）中的 gen-beaninfo 目标也会生成 BeanInfo 基类。您需要扩展这些基类以创建 BeanInfo 类。

如果忘记扩展 BeanInfo 基类，组件将无法正常使用，因为 JavaBeans 自省器将返回一个 BeanInfo 类，该类基于使用 Java 反射 API 检查该 Bean 时的结果。

Java Studio Creator 使用 BeanInfo 类作为与组件有关的静态元数据的唯一来源。有关详细信息，请参阅 DatePickerBeanInfo.java 源代码。请注意如何通过添加图像文件将图标与组件关联起来以及如何处理属性描述符。

设计时 JAR 文件也包含 DesignInfo 类。DesignInfo 类提供了有关组件的动态行为，而不是静态信息。样例 DatePickerDesignInfo.java 说明了如何在设计时（即，将新的日期选取器实例添加到页面上时）更改属性。该样例还说明了如何使用 Java Studio Creator 设计时 API 将 DateUtilConverter 链接到 DatePicker。此 API 扩展了标准 JavaBeans API，添加了一组丰富的新功能以在设计时处理组件和属性，以及为 IDE 提供了上下文菜单项、定制器以及扩展的属性编辑器。

通常放置在设计时 JAR 文件中的其他项包括属性编辑器、类别描述符以及本地化资源包。例如，在 DatePickerBeanInfo 中，DatePicker yearAlign 属性与 com.example.util.YearAlignPropertyEditor 关联在一起，后者也包含在设计时 JAR 文件中。有关详细信息，请参见样例 build.xml 文件中的 jar-dt 目标。

complib 中可以包含对 IDE 用户有用的其他可选项。这些项包括：

• Javadoc 文件：请参见 javadoc 和 complib ant 目标。
• 源文件：请参见 complib ant 目标，它说明了如何包括源代码 zip 文件。
• 帮助：最终将支持帮助文件，但是当前不支持这些文件。

组装 complib 文件是最后一步。首先，创建一个 JAR 清单文件，它包含一个指向 XML 配置文件的指针。在本示例中，complib-config.xml 包含与 complib 有关的所有元数据。

在本示例中，conf/complib-config.xml 文件包含一个指向用于国际化的 Java 属性 ResourceBundle 的指针。它在 IDE 的组件面板类别中显式地声明组件类。它还使用由 ant 复制任务替代的过滤器表达式。

最后，创建包含 JAR ant 任务的 complib 文件。有关详细信息，请参见 complib 目标。

按如下方式测试组装的组件库：

1. 打开“组件库管理器”对话框。在 IDE 中，从菜单栏中选择“工具”->“组件库管理器”（或者，也可以从组件面板类别的上下文菜单中选择“管理组件库”）。
2. 在“组件库管理器”对话框中单击“导入...”按钮以打开“导入组件库”对话框。
3. 浏览到 complib 文件并将其导入。
4. 从新导入的组件库中添加一个组件以测试该组件。

Java Studio Creator 2 使用导入的组件库并扩展包，从而将导入库中的组件添加到用户组件面板上（您可能需要打开组件面板类别才能看到新组件）。它还会将扩展的 complib 复制到当前用户目录 ~/.Creator/ 下的某个位置（请注意，此位置可能会发生更改）。

通过将组件添加到页面来对其进行测试。第一次将组件添加到页面上时，IDE 会将解压缩的 complib 复制到项目中，并创建对组件库的引用。您可以在“项目”窗口中的项目“库”节点下看到该引用。通过在“项目”窗口中选择项目节点的“属性”上下文菜单项，可以看到在项目中添加的库。

使用组件库时，请切记这些其他注意事项。

• 第一次导入 complib 时，IDE 将解压缩 complib 文件并将其扩展到 Java Studio Creator 用户目录的子目录中。例如，在 Java Studio Creator 2 中，会将其放在 ~/.Creator/2_0/complibs/ 下。但是，实际的 Java Studio Creator 用户目录的位置可能会发生更改。使用组件库的每个项目将其自己的副本保存在项目的某个子目录中，该目录是在第一次将特定组件库中的组件添加到项目中时创建的。
• 如果迭代开发某个组件，请考虑使用以下开发策略。首先，更改某些代码，生成新的 complib，将 complib 导入到 Java Studio Creator 中，然后在现有项目中测试新的代码。您可能需要显式地覆盖以前的项目 complib。要执行此操作，请将组件面板上显示的新导入 complib 中的组件添加到项目的页面上，然后撤消添加。此操作会使 IDE 使用项目中的新 complib 覆盖旧 complib。即使两个 complib 具有相同的标识符（uri、版本对），IDE 也会由于其使用时间戳而用新版本 complib 覆盖旧版本。
• 第三方开发者应使用 IDE 的 Java Studio Creator 设计时 API 来创建更丰富的设计时体验。
• 您可以设置命令行属性以指定初始组件库导入浏览目录。例如，在 Windows 系统上，您可以打开 DOS 提示符并执行：C:\Sun\Creator\bin\creator.exe -J-Dtoolbox.importStartDir=/cygwin/home/ edwingo/tmp。
• 在 Java Studio Creator 2 中，您可以通过将 complib 文件放在特殊目录中来自动安装组件库，该目录为：$RAVE_INSTALL_HOME/complibs_to_install/。下次运行 IDE 时，该目录中的 complib 文件将被自动安装到组件面板中。
• 确保可视组件的 BeanInfo 类扩展了生成的 BeanInfoBase 类。否则，在项目中添加可视组件时，可能会出现问题。即使通过执行用于样例组件的步骤开发了可视组件，如果其 BeanInfo 类未扩展 BeanInfoBase 类，新添加的组件可能会出现在“概要”窗口中，而不是可视设计器中，并且错误日志不显示任何异常。您可以忽略以下警告消息："You are trying to access file: complib-config.xml from the default package..."（您正在试图从缺省包中访问文件 complib-config.xml...），该消息可能会出现在 IDE 日志文件中。
• 现有通用 JavaServer Faces 组件（如 myfaces 和 ourfaces）需要进行额外的修改才可以在 IDE 中使用。通过添加额外的设计时代码，可以使某些通用组件能够正常使用；在其他情况下，您可能需要修改组件运行时代码。修改后，您可以将这些组件包装到一个 complib 文件中。有关准则，请参见“为 Java Studio Creator 编写定制组件”第 2 部分：设计时注意事项。有时，在“属性”窗口中未正确更新日期组件的属性。要强制进行更新，请在“属性”窗口中单击属性。某些日期组件的属性是只读的；只能使用 Java 代码 getter 方法来访问它们。

现在，您已经大致了解了创建组件库并将其用于 Java Studio Creator 2 IDE 的过程。您还了解了组成组件库的各种文件，以及对此类库中的组件执行生成、组装和测试操作的步骤。

您可以从 Java Studio Creator 2 IDE 更新中心下载本文中提到的包含源代码的样例组件。它们提供了一种非常好的方法来直接查看组件库的组成部分。

这是文章的第 1 部分（共 2 部分）。第 2 部分是“为 Java Studio Creator 编写定制组件”第 2 部分：设计时注意事项。

您可以通过各种不同的来源以了解有关组件和组件库的详细信息。

功能简介文章 Sun Java Studio Creator 2 的 Java Studio Creator 设计时 API 简要介绍了 API。您可能还想了解 Java Studio Creator 设计时 API 规范。

JavaServer Faces 组件简介介绍了定制现有 JavaServer Faces 标准组件与生成新的定制组件之间的区别。请阅读此文章以了解您可能需要生成自己的组件的原因，以及在您决定执行此操作时应切记的注意事项。

“为 Java Studio Creator 编写定制组件”第 2 部分：设计时注意事项为您编写自己的定制组件提供了所需的详细信息。

《J2EE 1.4 教程》的创建定制 UI 组件一章为您编写自己的组件提供了详细准则。

如何编写 JavaServer Faces 组件提供了一些编写组件的基本规则。

了解有关 JavaServer Faces 组件和 JavaBeans 的详细信息。

有关为开发者提供的教程、技术提示、文章、论坛、更新和专家建议，请访问 Sun Developer Network (SDN) 上的 Java Studio Creator 开发者资源，网址为 http://gceclub.sun.com.cn/prodtech/javatools/jscreator/。