2021SC@SDUSC

在这次博客中我是对transformation文件夹下的IncludeTransformer进行分析，在此之前我已经对CIncludeTransformer进行了了解与分析。

分析core文件夹（七）

• • IncludeTransformer.java（上）
  • • 1.总结
    • 2.属性：
    • 3.方法：
    • 4.其他说明：
    • • 构造函数：
      • 一些关于private，static，final的说明

IncludeTransformer.java（上）

1.总结

这个文件是一个简单的转换器，包括可解析的输入源(通过Cocoon的SourceResolver访问)。

这个转换器的一个有趣特性是，它实现了CacheableProcessingComponent接口，并提供了对缓存的完全支持。换句话说，如果给这个转换器的输入没有改变，并且所有包含的源都是(可缓存的)并且仍然有效，那么这个转换器将不会像CIncludeTransformer那样强制管道重新生成。

下面介绍了一些这个转换器的特性：

• 相对源解析
  • 包含使用相对URI指定的源文件将相对于源文档位置进行解析。这与XIncludeTransformer行为一致，但与CIncludeTransformer不同。
• 根元素剥离
  • 包含内容的根元素可以通过在include元素上指定strip-root="true"自动剥离。这与CIncludeTransformer提供的功能相同。
• 参数传递
  • 传递给包含的源的参数可以通过两种方式指定:第一种方式是将它们编码到源本身。另一种方法允许由转换器自动完成参数的编码，这样就可以很容易地传递包含& (amperstand)或= (equals)字符的参数名称或值，这些字符在uri中是保留字符。
• 后备元素
  • IncludeTransformer允许在include元素中指定回退元素。如果源包含导致异常，则将包含回退元素的XML内容，而不是源内容。回退元素可以嵌套包含元素。
• 并行处理
  • 这个转换器的另一个特性是它允许并行处理包含。通过将可选参数parallel设置为true，将在并行线程中处理(包括)各种包含的内容，而不是在一个线程中串行处理。默认情况下，并行处理是关闭的。
• 递归处理
  • 这个转换器允许递归处理包含。通过将可选参数recursive设置为true，将扫描包含的各种内容以查找包含元素，并以与传入XML事件相同的方式处理这些内容。这个参数可以在转换器定义中设置。这个特性类似于XInclude处理。默认情况下，递归处理是关闭的。

继承自AbstractTransformer

实现了Serviceable，Configurable，CacheableProcessingComponent接口

2.属性：

一些私有的静态的不可以修改的属性：

• private static final String NS_URI = "http://apache.org/cocoon/include/1.0";
  • 该转换器识别的元素的名称空间URI。
• private static final String INCLUDE_ELEMENT = "include";
  • 触发包含源的元素名。
• private static final String FALLBACK_ELEMENT = "fallback";
  • 定义回退内容的元素的名称。
• private static final String PARAMETER_ELEMENT = "parameter";
  • 定义包含子请求参数的元素名。
• private static final String SRC_ATTRIBUTE = "src";
  • 表示包含的源URI的属性名。
• private static final String MIME_ATTRIBUTE = "mime-type";
  • 包含org.apache.excalibur.xmlizer.XMLizer提示的mime类型属性的名称。
• private static final String PARSE_ATTRIBUTE = "parse";
  • 解析属性的名称，表示所包含的源处理的类型:xml或文本。
• private static final String STRIP_ROOT_ATTRIBUTE = "strip-root";
  • trip-root属性的名称，表示应该剥离所包含xml源的根元素。
• private static final String NAME_ATTRIBUTE = "name";
  • 属性名，表示参数名
• private static final String VALUE_ATTRIBUTE = "value";
  • 属性名，表示参数值
• private static final String ENCODING = "US-ASCII";
  • 用于参数名和值的编码。

其他属性：

• 全局配置：
  • protected ServiceManager manager;
    • 与此实例关联的ServiceManager实例。
  • private boolean defaultRecursive;
    • 控制递归的配置选项包括处理。
  • private boolean defaultParallel;
    • 配置选项控制并行(在多个线程)包括处理。
  • private boolean defaultRecursiveParallel;
    • 配置选项控制并行(在多个线程)包括处理递归包括。
  • protected String threadPool;
    • 要使用的线程池名称(用于并行处理)。
  • private String defaultKey;
    • 附加到缓存键的默认值。
• 当前配置：
  • protected SourceResolver resolver;
    • 用于解析包含uri的SourceResolver。
  • protected RequestAttributes attributes;
    • 在并行线程中使用的RequestAttributes。
  • protected Environment environment;
    • 在并行线程中使用的Environment}。
  • private Processor processor;
    • 在并行线程中使用的link Processor}。
  • private String key;
    • 要附加到缓存键的值。
• 当前状态：
  • protected MultiSourceValidity validity;
    • 与此请求关联的link SourceValidity实例。
  • private NamespacesTable namespaces;
    • 用于过滤命名空间声明的NamespacesTable。
  • private final IncludeXMLPipe pipe;
    • IncludeXMLPipe正在做所有的工作。

3.方法：

• public void service(ServiceManager manager)
  • 为这个实例设置可用的ServiceManager。
• public void configure(Configuration configuration)
  • 这个方法重载的是接口Configurable里的。
  • 这个接口应该由需要在初始化之前配置自定义参数的类来实现。围绕可配置的约定是实例化实体必须在它生效之前调用configure方法。
  • 为递归、并行、递归并行读取配置节点，并从配置节点中读取线程池名称。
• public void setup(SourceResolver resolver, Map om, String src, Parameters parameters)
  • 在它的管道和当前请求的上下文中设置这个组件实例。
  • 读取地图参数，初始化转换器状态，将根目录包括管道设置为消费者。这里不会使用setter方法——它们被重写了。
• public void setConsumer(XMLConsumer consumer)
  • 设置XMLConsumer。
• public void setContentHandler(ContentHandler handler)
  • 设置ContentHandler上下文处理器。
• public void setLexicalHandler(LexicalHandler handler)
  • 设置LexicalHandler。
• public void recycle()
  • 回收此组件实例。
  • 将命名空间（namespaces）和有效性（validity）设置为null。确保所有线程完成它们的工作，当所有线程完成处理并释放它们的source时，解析器可以被取消。
• public void startDocument()
  • 接收XML文档开始的通知。
  • 确保我们在处理过程中的有效性
• public void endDocument()
  • 接收XML文档结束的通知。
  • 确保有效性在最后是“关闭的”
• public void startPrefixMapping(String prefix, String nsuri)
  • 接收前缀映射开始的通知。
  • 如果NS_URI与nsuri相等，跳过当前前缀的映射，因为我们知道他
  • 否则，映射当前前缀，因为我们不知道他
• public void endPrefixMapping(String prefix)
  • 接收前缀映射结束通知。
• public Serializable getKey()
  • 返回与此转换关联的缓存键。
  • 在根据环境(请求参数、会话属性等)包含动态内容的“cocoon://”源时，使用关键sitemap参数向转换器提供这样的环境值以包含到关键中是有意义的。
  • 在包含“cocoon://”或其他动态源的情况下，理想情况下必须包含“cocoon://”源的ProcessingPipelineKey，但这是不可能的，因为目前我们还不知道哪些源会被包含到响应中。因此，建议使用站点地图参数提供关键字。
• public SourceValidity getValidity()
  • 生成(或返回)用于可能验证缓存生成的SourceValidity实例。

4.其他说明：

构造函数：

//创建一个新的IncludeTransformer实例。
public IncludeTransformer() {
    pipe = new IncludeXMLPipe();
}

一些关于private，static，final的说明

• public: 表示公共的，其他类或者该类的子类也允许访问被public修饰的属性或方法
• protected: 表示受保护的，不允许其他类访问被protected修饰的属性或方法
  但是 ，它允许子类访问被protected修饰的属性或方法（不允许其他类，允许子类访问）
• private: 表示私有的，不允许本类之外的类访问，它的子类也不允许访问被private修饰的属性或方法（本类之内访问，子类也不可以访问）
• static：表示静态的，是属于某个类的，不属于某个对象的，是对象公有的
• final: 最终的，不允许修改，一旦赋值后被final修饰的东西就不再允许修改了

关于这个java文件还没有分析完，这个转换器类里面还有两个内部类将在下一篇博客中进行分析。