深入浅出 jackrabbit 三 创建 document

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

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

　　Java代码　　　

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方法：

ava代码　　　

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：

　　Java代码　　　

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

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

　　Java代码　　　

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的注释

　　Java代码　　　

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的方法：

　　Java代码　　　

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方法：

　　Java代码　　　

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

　　Java代码　　　

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，我们看看里面是什么东西吧：

　　Java代码　　　

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