深入浅出 jackrabbit 3 创建 document

/**
*作者：ahuaxuan 张荣华
*日期：2009-07-01
**/

在上一篇文章中，ahuaxuan描述了jackrabbit中创建index的主体流程，同时也曾提到，在创建流程中有一个方法非常重要，它影响着整个query体系，这个方法便是createDocument。在本文中，ahuaxuan将和大家一起来探讨如何根据一个node来创建对应的document。

二话不说，直接切入正题，让我们首先来看看SearchIndex#createDocument方法，从这个方法里包含着创建document的逻辑，方法中加入了ahuaxuan的注释：

protected Document createDocument(NodeState node,
                                      NamespaceMappings nsMappings,
                                      IndexFormatVersion indexFormatVersion)
            throws RepositoryException {
//创建NodeIndexer，Creates a lucene Document object from a javax.jcr.Node.
        NodeIndexer indexer = new NodeIndexer(node,
                getContext().getItemStateManager(), nsMappings, extractor);
//设置是否需要高亮，这个高亮很容易让人迷惑，indexer.setSupportHighlighting(supportHighlighting);
//设置indexconfig
        indexer.setIndexingConfiguration(indexingConfig);
        indexer.setIndexFormatVersion(indexFormatVersion);

//用node对象创建document
        Document doc = indexer.createDoc();
        mergeAggregatedNodeIndexes(node, doc);
        return doc;
}

从上面这段代码，我们可以看出，最重要的方法应该是indexer.createDoc();其他方法都是配角。那么就让我们进入这个createDoc方法：

protected Document createDoc() throws RepositoryException {
        Document doc = new Document();

        doc.setBoost(getNodeBoost());

        // special fields
        // UUID
//代码第一段，负责添加一些固定的field到document中，uuid，parent，label
        doc.add(new Field(FieldNames.UUID, node.getNodeId().getUUID().toString(), Field.Store.YES, Field.Index.NO_NORMS, Field.TermVector.NO));
        try {
            // parent UUID
            if (node.getParentId() == null) {
                // root node
                doc.add(new Field(FieldNames.PARENT, "", Field.Store.YES, Field.Index.NO_NORMS, Field.TermVector.NO));
                doc.add(new Field(FieldNames.LABEL, "", Field.Store.NO, Field.Index.NO_NORMS, Field.TermVector.NO));
            } else {
                doc.add(new Field(FieldNames.PARENT, node.getParentId().toString(), Field.Store.YES, Field.Index.NO_NORMS, Field.TermVector.NO));
                NodeState parent = (NodeState) stateProvider.getItemState(node.getParentId());
                NodeState.ChildNodeEntry child = parent.getChildNodeEntry(node.getNodeId());
                if (child == null) {
                    // this can only happen when jackrabbit
                    // is running in a cluster.
                    throw new RepositoryException("Missing child node entry " +
                            "for node with id: " + node.getNodeId());
                }
                String name = resolver.getJCRName(child.getName());
                doc.add(new Field(FieldNames.LABEL, name, Field.Store.NO, Field.Index.NO_NORMS, Field.TermVector.NO));
            }
        } catch (NoSuchItemStateException e) {
            throwRepositoryException(e);
        } catch (ItemStateException e) {
            throwRepositoryException(e);
        } catch (NamespaceException e) {
            // will never happen, because this.mappings will dynamically add
            // unknown uri<->prefix mappings
        }
/////////////////////////代码第二段，负责添加一个node的property到document中。
        Set props = node.getPropertyNames();
        for (Iterator it = props.iterator(); it.hasNext();) {
            Name propName = (Name) it.next();
            PropertyId id = new PropertyId(node.getNodeId(), propName);
//遍历node的property并一一创建field
            try {
                PropertyState propState = (PropertyState) stateProvider.getItemState(id);
                
                // add each property to the _PROPERTIES_SET for searching
                // beginning with V2
                if (indexFormatVersion.getVersion()
                        >= IndexFormatVersion.V2.getVersion()) {					
				//添加field：_:PROPERTIES_SET
                    addPropertyName(doc, propState.getName());
                }
                //得到property的values，准备一个个value做field
                InternalValue[] values = propState.getValues();
                for (int i = 0; i < values.length; i++) {
					//一个尤其需要注意的方法，该方法中会根据value的类型//创建不同的filed。
                    addValue(doc, values[i], propState.getName());
                }
                if (values.length > 1) {
                    // real multi-valued
                    addMVPName(doc, propState.getName());
                }
            } catch (NoSuchItemStateException e) {
                throwRepositoryException(e);
            } catch (ItemStateException e) {
                throwRepositoryException(e);
            }
        }
        return doc;
    }

从上面这段代码，我们可以看出一个document有很多个field组成，其中有一些是必不可少，也有一些是根据node属性决定的。那么我们就来统计一下有多少个field被创建了，其实这个也是本文的主要目的，一旦我们清晰的知道有哪里信息被放到field中，那么对于我们反思search过程有莫大的好处。而且ahuaxuan将这些field分成了两个部分，一个部分属性node的信息，还有一部分属性node的property信息。

一，node
1 fieldname: uuid，值得注意的是该field既存储也索引
doc.add(new Field(FieldNames.UUID, node.getNodeId().getUUID().toString(), Field.Store.YES, Field.Index.NO_NORMS, Field.TermVector.NO));

2 fieldname: PARENT
和uuid类似

3 fieldname: LABEL，该field不存储，但是索引
new Field(FieldNames.LABEL, name, Field.Store.NO, Field.Index.NO_NORMS, Field.TermVector.NO)

二 property

4 fieldname: _:PROPERTIES_SET
这个属性比较奇特，因为这个属性的设置在for循环中，也就是名字为_:PROPERTIES_SET的field的值有多个，它的值是field的name，不过lucene最后会把同名的field合并。这个属性索引但不存储，而且还有一个条件判断，只有在jackrabbit1.4以上才会添加这个field，为什么加这个field呢，官方的解释是在某些查询中这个field会加快查询速度。
new Field(FieldNames.PROPERTIES_SET, fieldName, Field.Store.NO, Field.Index.NO_NORMS)

5 fieldname: _:MVP
当一个property对应多个value的时候，那么就会创建这个field：
new Field(FieldNames.MVP, propName, Field.Store.NO, Field.Index.UN_TOKENIZED, Field.TermVector.NO)

重点：最后一个需要说明的field是下面这段代码产生的field：

InternalValue[] values = propState.getValues();
                for (int i = 0; i < values.length; i++) {
                    addValue(doc, values[i], propState.getName());
                }

这段代码ahuaxuan之前已经加了一点注释，下面我们来深入到方法的内部来看看这个方法究竟会创建什么样的field。下面这个方法看上去有点长，好像很会创建很多种field的样子，非也，下面这段代码其实只会创建3种field。

private void addValue(Document doc, InternalValue value, Name name) {
        String fieldName = name.getLocalName();
        try {
            fieldName = resolver.getJCRName(name);
        } catch (NamespaceException e) {
            // will never happen
        }
        switch (value.getType()) {
            case PropertyType.BINARY:
                if (isIndexed(name)) {
//很重要，如果是二进制的property，那么在这个方法里会被解析
                    addBinaryValue(doc, fieldName, value.getBLOBFileValue());
                }
                break;
            case PropertyType.BOOLEAN:
                if (isIndexed(name)) {
                    addBooleanValue(doc, fieldName, Boolean.valueOf(value.getBoolean()));
                }
                break;
            case PropertyType.DATE:
                if (isIndexed(name)) {
                    addCalendarValue(doc, fieldName, value.getDate());
                }
                break;
            case PropertyType.DOUBLE:
                if (isIndexed(name)) {
                    addDoubleValue(doc, fieldName, new Double(value.getDouble()));
                }
                break;
            case PropertyType.LONG:
                if (isIndexed(name)) {
                    addLongValue(doc, fieldName, new Long(value.getLong()));
                }
                break;
            case PropertyType.REFERENCE:
                if (isIndexed(name)) {
                    addReferenceValue(doc, fieldName, value.getUUID());
                }
                break;
            case PropertyType.PATH:
                if (isIndexed(name)) {
                    addPathValue(doc, fieldName, value.getPath());
                }
                break;
            case PropertyType.STRING:
//很重要，普通string的property也会成为一种field，而binary和//string之间的case其实都是一种field。也就是说这个方法里负责创建3种//field。
                if (isIndexed(name)) {
                    // never fulltext index jcr:uuid String
                    if (name.equals(NameConstants.JCR_UUID)) {
                        addStringValue(doc, fieldName, value.getString(),
                                false, false, DEFAULT_BOOST);
                    } else {
                        addStringValue(doc, fieldName, value.getString(),
                                true, isIncludedInNodeIndex(name),
                                getPropertyBoost(name));
                    }
                }
                break;
            case PropertyType.NAME:
                // jcr:primaryType and jcr:mixinTypes are required for correct
                // node type resolution in queries
                if (isIndexed(name) ||
                        name.equals(NameConstants.JCR_PRIMARYTYPE) ||
                        name.equals(NameConstants.JCR_MIXINTYPES)) {
                    addNameValue(doc, fieldName, value.getQName());
                }
                break;
            default:
                throw new IllegalArgumentException("illegal internal value type");
        }
    }

通过上面这段示例代码，我们已经知道，addValue方法是创建3种field，下面我们来一一查看创建这3种field的方法：

NodeIndexer#addBinaryValue()

NodeIndexer#addBooleanValue()

NodeIndexer#addStringValue()

首先登场的是addBinaryValue,该方法之操作nt：resource的node，同时需要拿到binary的type和encoding，然后从文件中提取文本。
方法中已经加入了ahuaxuan的注释

protected void addBinaryValue(Document doc,
                                  String fieldName,
                                  Object internalValue) {
        // 'check' if node is of type nt:resource
        try {
            String jcrData = mappings.getPrefix(Name.NS_JCR_URI) + ":data";
            if (!jcrData.equals(fieldName)) {
                // don't know how to index
                return;
            }

            InternalValue typeValue = getValue(NameConstants.JCR_MIMETYPE);
            if (typeValue != null) {
				//拿到文本的type，pdf，doc，等等
                String type = typeValue.getString();

                // jcr:encoding is not mandatory
					//拿到编码类型
                String encoding = null;
                InternalValue encodingValue = getValue(NameConstants.JCR_ENCODING);
                if (encodingValue != null) {
                    encoding = encodingValue.getString();
                }
			
                InputStream stream =
                        ((BLOBFileValue) internalValue).getStream();
				//对而进制流进行提取，这里我们暂时把这个操作当成非异步//操作来理解
                Reader reader = extractor.extractText(stream, type, encoding);
				//创建field
                doc.add(createFulltextField(reader));
            }
        } catch (Exception e) {
            ………………
        }
}

从这个注释的流程来看，最重要的应该是createFulltextField方法，那么我们再进去看看，我们就会发现创建field的方法：

new Field(FieldNames.FULLTEXT, value, stored,
                    Field.Index.TOKENIZED, Field.TermVector.WITH_OFFSET)

(注意这里的WITH_OFFSET,证明FULLTEXT确实是把term对应的offset放到索引中的。在查询FULLTEXT的时候将会用到这个属性，这样做的目的是避免实时分词，提高高亮的性能)
所以这个方法中创建了一个新的field类型，FieldNames.FULLTEXT
它的值为：_:FULLTEXT，这样我们就得到了第6种field，_:FULLTEXT

接下来，我们看看addBooleanValue方法：

Field field = new Field(FieldNames.PROPERTIES,
                FieldNames.createNamedValue(fieldName, internalValue),
                store ? Field.Store.YES : Field.Store.NO, Field.Index.NO_NORMS,
                Field.TermVector.NO);

简单的不能再简单了，这里又多了一种field，它的name是FieldNames.PROPERTIES，他的值是：_:PROPERTIES，这样我们就得到了第7种field：_:PROPERTIES。同样，需要注意的是，这个field可能会被创建多次，如果你的node中有同类型的多个boolean值的话。而且更需要注意的是不只是BOOLEAN，还有DATE，DOUBLE，LONG等等，都是这个name，lucene将会把这些同名的field的值最后拼接起来，形成一个field。

那么我们再来看看上面提到的第3个方法：
addStringValue

protected void addStringValue(Document doc, String fieldName,
                                  Object internalValue, boolean tokenized,
                                  boolean includeInNodeIndex, float boost) {

        // simple String
        String stringValue = (String) internalValue;
//先把这个stringvalue加到_:PROPERTIES这个field中。
        doc.add(createFieldWithoutNorms(fieldName, stringValue, false));
//jcr:uuid这个属性也是string，但是不需要执行下面的if，但是除这个属性之外的其他属性，执行下面的放并创建一个field。
        if (tokenized) {
            if (stringValue.length() == 0) {
                return;
            }
            // create fulltext index on property
            int idx = fieldName.indexOf(':');
 //创建fieldname
            fieldName = fieldName.substring(0, idx + 1)
                    + FieldNames.FULLTEXT_PREFIX + fieldName.substring(idx + 1);
            Field f = new Field(fieldName, stringValue,
                    Field.Store.NO,
                    Field.Index.TOKENIZED,
                    Field.TermVector.NO);
		//注意这里的Field.TermVector是NO，所以这个property如
//果需要高亮，那么不可避免再次实时分词，这一点在查询的代码里写的很清//楚。            

f.setBoost(boost);
            doc.add(f);
			//这段代码好奇怪哦，为啥对这个string要创建fulltext呢？
            if (includeInNodeIndex) {
                // also create fulltext index of this value
                doc.add(createFulltextField(stringValue));
            }
        }
    }

从上面这个方法我们也大概看出一点名堂了，一般的string类型的property也作了单独的field。而且还有一个很好玩的，如果includeInNodeIndex=true（表示这个property应该放到fulltext中去，显然这个是在property定义的时候决定的，这个值来自于配置文件，如果没有做特别的配置，那么这个值为false，详见：IndexingRule）,那么会执行，createFulltextField，我们看看里面是什么东西吧：

protected Field createFulltextField(String value) {
        if (supportHighlighting) {
			//还记得supportHighlighting这个参数不，这个表示如果需要//高亮，就会把string类型的property加到fulltext中，同时保存offset。
            
            Field.Store stored;
            if (value.length() > 0x4000) {
				//超过16k还需要压缩一下
                stored = Field.Store.COMPRESS;
            } else {
                stored = Field.Store.YES;
            }
            return new Field(FieldNames.FULLTEXT, value, stored,
                    Field.Index.TOKENIZED, Field.TermVector.WITH_OFFSETS);
        } else {
			//不支持高亮就不保存offset
            return new Field(FieldNames.FULLTEXT, value,
                    Field.Store.NO, Field.Index.TOKENIZED);
        }
    }

Hoho，一个普通的string类型的property居然加到fulltext中去了。并且如果支持高亮，还需要保存它的offset，这样做的目的是什么呢，貌似我们在这里找不到答案，那我们就等到分析query的时候再来回答这个问题。

到目前为止，就ahuaxuan的分析而言，field的种类就是以上这么多种了，我们再来总结一下：

引用

1． Uuid（node的uuid）
2． PARENT（parent node的uuid）
3． LABEL（node name）
4． _:PROPERTIES_SET（properties name）
5． _:MVP(multi value property name)
6． _:FULLTEXT(jcr:data which extract from pdf, doc….)
7． _:PROPERTIES(properties name and value)
8. *:FULL:*(string property name)：(string property value)

这样我们就明白，到底node的哪些属性被添加到索引中去了，这样为我们理解查询提供了有力的依据。

接下来，我们会去了解一下把document添加到indexwriter的流程，这个流程中隐藏着很多的秘密，to be continue