Lucene学习(22)

关于FieldInfos类和FieldInfo类。

FieldInfo类与一个Document中的一个Field相对应，而FieldInfos类又是多个FieldInfo的容器，对每个Document的所有Field对应的FieldInfo进行管理。

FieldInfos类和FieldInfo类之间的关系，恰似SegmentInfos类(可以参考文章 Lucene-2.2.0 源代码阅读学习(18))和SegmentInfo类(可以参考文章 Lucene-2.2.0 源代码阅读学习(19))之间的关系。

FieldInfo类的实现比较简单，该类的定义如下所示：

package org.apache.lucene.index;

final class FieldInfo {
	String name; // 一个Field的名称 
	boolean isIndexed; // 该Field是否被索引 
	int number; // 该Field的编号 

	// 是否存储该Field的词条向量 
	boolean storeTermVector;
	boolean storeOffsetWithTermVector;
	boolean storePositionWithTermVector;

	boolean omitNorms; // 是否忽略与被索引的该Field相关的norm文件信息 

	boolean storePayloads; // 是否该Field存储与词条位置相关的Payload 

	// 构造一个FieldInfo对象 

	FieldInfo(String na, boolean tk, int nu, boolean storeTermVector,
			boolean storePositionWithTermVector,
			boolean storeOffsetWithTermVector, boolean omitNorms,
			boolean storePayloads) {
		name = na;
		isIndexed = tk;
		number = nu;
		this.storeTermVector = storeTermVector;
		this.storeOffsetWithTermVector = storeOffsetWithTermVector;
		this.storePositionWithTermVector = storePositionWithTermVector;
		this.omitNorms = omitNorms;
		this.storePayloads = storePayloads;
	}
}

上面就是2.2.0版本中FieldInfo类的全部定义。

下面是FieldInfos了的定义了，该类主要是通过FieldInfo来管理一个Document中的全部Field，源代码如下所示：

package org.apache.lucene.index;

import org.apache.lucene.document.Document;
import org.apache.lucene.document.Fieldable;
import org.apache.lucene.store.Directory;
import org.apache.lucene.store.IndexInput;
import org.apache.lucene.store.IndexOutput;

import java.io.IOException;
import java.util.*;

// FieldInfo描述的是Document中的Field的信息，而FieldInfos类是用来管理一个个的FieldInfo的。 
final class FieldInfos {

	// 下面一组byte成员，使用十六进制数初始化，用来管理FieldInfo的属性 

	static final byte IS_INDEXED = 0x1; // 是否索引 
	static final byte STORE_TERMVECTOR = 0x2; // 是否存储词条向量 
	static final byte STORE_POSITIONS_WITH_TERMVECTOR = 0x4; // 是否存储与词条向量相关的位置 
	static final byte STORE_OFFSET_WITH_TERMVECTOR = 0x8; // 是否存储与词条向量相关的offset 
	static final byte OMIT_NORMS = 0x10; // 是否存储被忽略的norms 
	static final byte STORE_PAYLOADS = 0x20; // 是否存储Payload 

	private ArrayList byNumber = new ArrayList(); //   byNumber是通过编号，用来存放FieldInfo的列表 
	private HashMap byName = new HashMap(); //   byNname是通过名称，用来存放FieldInfo的列表 

	FieldInfos() {
	} //   没有参数的FieldInfos的构造函数 

	//    通过索引目录d和一个索引输入流name构造一个FieldInfos对象 
	FieldInfos(Directory d, String name) throws IOException {
		IndexInput input = d.openInput(name);
		try {
			read(input); //   input输入流已打开，从索引目录中读取 
		} finally {
			input.close();
		}
	}

	//   为一个Document添加Field的信息(这种添加和直接向Document中添加Field不一样，这次添加的不是一些固有信息，是一些更详细的补充信息) 
	public void add(Document doc) {
		List fields = doc.getFields(); // 先获取到该Document中已经添加进去的所有Field 
		Iterator fieldIterator = fields.iterator();
		while (fieldIterator.hasNext()) {
			Fieldable field = (Fieldable) fieldIterator.next();
			add(field.name(), field.isIndexed(), field.isTermVectorStored(),
					field.isStorePositionWithTermVector(), field
							.isStoreOffsetWithTermVector(), field
							.getOmitNorms()); // 传参，调用核心的add方法执行添加 
		}
	}

	/** 
	 * 添加被索引的Field，需要指定是否具有词条向量 
	 */
	public void addIndexed(Collection names, boolean storeTermVectors,
			boolean storePositionWithTermVector,
			boolean storeOffsetWithTermVector) {
		Iterator i = names.iterator();
		while (i.hasNext()) {
			add((String) i.next(), true, storeTermVectors,
					storePositionWithTermVector, storeOffsetWithTermVector);
		}
	}

	/** 
	 * 当Field没有存储词条向量，添加Field 
	 * 
	 * @param names The names of the fields 
	 * @param isIndexed Whether the fields are indexed or not 
	 * 
	 * @see #add(String, boolean) 
	 */
	public void add(Collection names, boolean isIndexed) {
		Iterator i = names.iterator();
		while (i.hasNext()) {
			add((String) i.next(), isIndexed);
		}
	}

	/** 
	 * Calls 5 parameter add with false for all TermVector parameters. 
	 * 
	 * @param name The name of the Fieldable 
	 * @param isIndexed true if the field is indexed 
	 * @see #add(String, boolean, boolean, boolean, boolean) 
	 */
	public void add(String name, boolean isIndexed) {
		add(name, isIndexed, false, false, false, false);
	}

	/** 
	 * Calls 5 parameter add with false for term vector positions and offsets. 
	 * 
	 * @param name The name of the field 
	 * @param isIndexed true if the field is indexed 
	 * @param storeTermVector true if the term vector should be stored 
	 */
	public void add(String name, boolean isIndexed, boolean storeTermVector) {
		add(name, isIndexed, storeTermVector, false, false, false);
	}

	/** If the field is not yet known, adds it. If it is known, checks to make 
	 * sure that the isIndexed flag is the same as was given previously for this 
	 * field. If not - marks it as being indexed. Same goes for the TermVector 
	 * parameters. 
	 * 
	 * @param name The name of the field 
	 * @param isIndexed true if the field is indexed 
	 * @param storeTermVector true if the term vector should be stored 
	 * @param storePositionWithTermVector true if the term vector with positions should be stored 
	 * @param storeOffsetWithTermVector true if the term vector with offsets should be stored 
	 */
	public void add(String name, boolean isIndexed, boolean storeTermVector,
			boolean storePositionWithTermVector,
			boolean storeOffsetWithTermVector) {

		add(name, isIndexed, storeTermVector, storePositionWithTermVector,
				storeOffsetWithTermVector, false);
	}

	/** If the field is not yet known, adds it. If it is known, checks to make 
	 * sure that the isIndexed flag is the same as was given previously for this 
	 * field. If not - marks it as being indexed. Same goes for the TermVector 
	 * parameters. 
	 * 
	 * @param name The name of the field 
	 * @param isIndexed true if the field is indexed 
	 * @param storeTermVector true if the term vector should be stored 
	 * @param storePositionWithTermVector true if the term vector with positions should be stored 
	 * @param storeOffsetWithTermVector true if the term vector with offsets should be stored 
	 * @param omitNorms true if the norms for the indexed field should be omitted 
	 */
	public void add(String name, boolean isIndexed, boolean storeTermVector,
			boolean storePositionWithTermVector,
			boolean storeOffsetWithTermVector, boolean omitNorms) {
		add(name, isIndexed, storeTermVector, storePositionWithTermVector,
				storeOffsetWithTermVector, omitNorms, false);
	}

	/** 如果该Field没有被添加过，则添加它。如果已经添加过，核查后确保它的是否被索引标志位与已经存在的一致，如果是“不索引”标志，则修改标志位为true. 
	 *该add添加方法才是最核心的实现方法。 
	 * @param name The name of the field 
	 * @param isIndexed true if the field is indexed 
	 * @param storeTermVector true if the term vector should be stored 
	 * @param storePositionWithTermVector true if the term vector with positions should be stored 
	 * @param storeOffsetWithTermVector true if the term vector with offsets should be stored 
	 * @param omitNorms true if the norms for the indexed field should be omitted 
	 * @param storePayloads true if payloads should be stored for this field 
	 */
	public FieldInfo add(String name, boolean isIndexed,
			boolean storeTermVector, boolean storePositionWithTermVector,
			boolean storeOffsetWithTermVector, boolean omitNorms,
			boolean storePayloads) {
		FieldInfo fi = fieldInfo(name); //   根据指定的name构造一个FieldInfo对象 
		if (fi == null) { // 如果构造的FieldInfo为null，则调用addInternal()方法，重新构造一个 
			return addInternal(name, isIndexed, storeTermVector,
					storePositionWithTermVector, storeOffsetWithTermVector,
					omitNorms, storePayloads);
		} else { // 如果构造的FieldInfo不为null(即已经存在一个相同name的FieldInfo) 
			if (fi.isIndexed != isIndexed) { // 如果存在的FieldInfo被索引 
				fi.isIndexed = true; // 一旦被索引了，总是索引 
			}
			if (fi.storeTermVector != storeTermVector) {
				fi.storeTermVector = true; // 一旦存储词条向量，总是存储 
			}
			if (fi.storePositionWithTermVector != storePositionWithTermVector) {
				fi.storePositionWithTermVector = true; // once vector, always vector 
			}
			if (fi.storeOffsetWithTermVector != storeOffsetWithTermVector) {
				fi.storeOffsetWithTermVector = true; // once vector, always vector 
			}
			if (fi.omitNorms != omitNorms) {
				fi.omitNorms = false; // 一旦存储norms，则总是存储norms 
			}
			if (fi.storePayloads != storePayloads) {
				fi.storePayloads = true;
			}

		}
		return fi; // 返回一个FieldInfo对象 
	}

	private FieldInfo addInternal(String name, boolean isIndexed,
			boolean storeTermVector, boolean storePositionWithTermVector,
			boolean storeOffsetWithTermVector, boolean omitNorms,
			boolean storePayloads) {
		FieldInfo fi = new FieldInfo(name, isIndexed, byNumber.size(),
				storeTermVector, storePositionWithTermVector,
				storeOffsetWithTermVector, omitNorms, storePayloads);
		byNumber.add(fi); // byNumber是一个List，将构造的FieldInfo加入到列表中 
		byName.put(name, fi); // byName是一个HashMap，其中的键值对<name,fi>表示一个名字为键，一个FieldInfo对象的引用作为值 
		return fi;
	}

	public int fieldNumber(String fieldName) { // 根据指定的Field的名称，获取该Field的编号 
		try {
			FieldInfo fi = fieldInfo(fieldName);
			if (fi != null)
				return fi.number;
		} catch (IndexOutOfBoundsException ioobe) {
			return -1;
		}
		return -1;
	}

	public FieldInfo fieldInfo(String fieldName) { // 根据指定的Field的名称，从byName列表中取出该Field 
		return (FieldInfo) byName.get(fieldName);
	}

	//   根据指定的编号，获取Field的名称name 
	public String fieldName(int fieldNumber) {
		try {
			return fieldInfo(fieldNumber).name;
		} catch (NullPointerException npe) {
			return "";
		}
	}

	// 根据指定的Field的编号，获取一个FieldInfo对象 
	public FieldInfo fieldInfo(int fieldNumber) {
		try {
			return (FieldInfo) byNumber.get(fieldNumber); // 从byNymber列表中取出索引为指定fieldNumber的FieldInfo对象 
		} catch (IndexOutOfBoundsException ioobe) {
			return null;
		}
	}

	public int size() { // 计算byName这个HashMap的大小 
		return byNumber.size();
	}

	public boolean hasVectors() { //    返回byName这个HashMap中FieldInfo指定对应的Field不存储词条向量的标志值，即false 
		boolean hasVectors = false;
		for (int i = 0; i < size(); i++) {
			if (fieldInfo(i).storeTermVector) {
				hasVectors = true;
				break;
			}
		}
		return hasVectors;
	}

	public void write(Directory d, String name) throws IOException { // 将FieldInfo的信息输出到索引目录中，name是索引目录中存在的索引段文件名segments.fnm(可以参考文章 Lucene-2.2.0 源代码阅读学习(21) 中，DocumentWriter的addDocument()方法) 
		IndexOutput output = d.createOutput(name);
		try {
			write(output); // 调用下面的write方法，对FieldInfo的信息进行格式化(输出)写入索引目录 
		} finally {
			output.close();
		}
	}

	public void write(IndexOutput output) throws IOException { // 对FieldInfo的信息进行格式化(输出)写入索引目录 
		output.writeVInt(size());
		for (int i = 0; i < size(); i++) {
			FieldInfo fi = fieldInfo(i);
			byte bits = 0x0;
			if (fi.isIndexed)
				bits |= IS_INDEXED;
			if (fi.storeTermVector)
				bits |= STORE_TERMVECTOR;
			if (fi.storePositionWithTermVector)
				bits |= STORE_POSITIONS_WITH_TERMVECTOR;
			if (fi.storeOffsetWithTermVector)
				bits |= STORE_OFFSET_WITH_TERMVECTOR;
			if (fi.omitNorms)
				bits |= OMIT_NORMS;
			if (fi.storePayloads)
				bits |= STORE_PAYLOADS;
			output.writeString(fi.name);
			output.writeByte(bits);
		}
	}

	private void read(IndexInput input) throws IOException { // 通过打开一个输入流，读取FieldInfo的信息 
		int size = input.readVInt();//read in the size 
		for (int i = 0; i < size; i++) {
			String name = input.readString().intern();
			byte bits = input.readByte();
			boolean isIndexed = (bits & IS_INDEXED) != 0;
			boolean storeTermVector = (bits & STORE_TERMVECTOR) != 0;
			boolean storePositionsWithTermVector = (bits & STORE_POSITIONS_WITH_TERMVECTOR) != 0;
			boolean storeOffsetWithTermVector = (bits & STORE_OFFSET_WITH_TERMVECTOR) != 0;
			boolean omitNorms = (bits & OMIT_NORMS) != 0;
			boolean storePayloads = (bits & STORE_PAYLOADS) != 0;

			addInternal(name, isIndexed, storeTermVector,
					storePositionsWithTermVector, storeOffsetWithTermVector,
					omitNorms, storePayloads); //   调用addInternal()在内存中构造一个FieldInfo对象，对它进行管理 
		}
	}

}

对FieldInfo类和FieldInfos类进行总结：

1、FieldInfo作为一个实体，保存了Field的一些主要的信息；

2、因为对Field的操作比较频繁，而每次管理都在内存中加载FieldInfo这个轻量级但信息很重要的对象，能够大大提高建立索引的速度；

3、FieldInfos包含的信息比较丰富，通过一个FieldInfo对象，调出Document中的Field到内存中，对每个Field进行详细的管理。

4、FieldInfos支持独立从索引目录中读取Document中的信息(主要根据Document参数，管理其中的Field)，然后再写回到索引目录。

综合总结：

FieldInfos是对Document中的Field进行管理的，它主要是在内存中进行管理，然后写入到索引目录中。具体地，它所拥有的信息都被写入了一个与索引段文件相关的segments.fnm文件中(可以参考文章 Lucene-2.2.0 源代码阅读学习(21) ，在DocumentWriter类的addDocument()方法中可以看到)

DocumnetWriter类的实现，是在FieldInfos类的基础上。FieldInfos类对Document的所有的Field的静态信息进行管理，而DocumentWriter类表现出了更强大的管理Document的功能，主要是对Field进行了一些高级的操作，比如使用 Analyzer分析器进行分词、对切分出来的词条进行排序(文档倒排)等等。

下一步，就要仔细研究DocumnetWriter类了。