honeymoose
/
OpenSearch
mirror of https://github.com/honeymoose/OpenSearch.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Make BytesValues documentation clearer about BytesRef ownership.

This commit is contained in:
Adrien Grand 2013-08-28 14:40:30 +02:00
parent e6f014bd62
commit b63af53313
1 changed files with 24 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
src/main/java/org/elasticsearch/index/fielddata/BytesValues.java
View File

@ -70,7 +70,12 @@ public abstract class BytesValues {
/**
* Returns the bytes value for the docId, with the provided "ret" which will be filled with the
* result which will also be returned. If there is no value for this docId, the length will be 0.
* Note, the bytes are not "safe".
* Implementations can either change the {@link BytesRef#bytes bytes reference} of the {@link BytesRef}
* to point to an internal structure or modify the content of the {@link BytesRef} but should
* always do it in a consistent way. For example, it is illegal to change the bytes content in
* some call and to change the reference to point to an internal structure in another call, this
* will lead to bugs. It is also illegal for callers to write into the {@link BytesRef#bytes bytes}
* after this method has returned.
*/
public abstract BytesRef getValueScratch(int docId, BytesRef ret);
@ -91,10 +96,22 @@ public abstract class BytesValues {
public static interface Iter {
/**
* Returns whether this iterator still contains elements.
*/
boolean hasNext();
/**
* Returns the next element of this iterator. Please note that the returned bytes may be
* reused across invocations so they should be copied for later reference. The behavior of
* this method is undefined if the iterator is exhausted.
*/
BytesRef next();
/**
* Returns the hash value of the last {@link BytesRef} returned by {@link #next()}. The
* behavior is undefined if this iterator is not positioned or exhausted.
*/
int hash();
public static class Empty implements Iter {
@ -266,7 +283,12 @@ public abstract class BytesValues {
/**
* Returns the bytes value for the docId, with the provided "ret" which will be filled with the
* result which will also be returned. If there is no value for this docId, the length will be 0.
* Note, the bytes are not "safe".
* Implementations can either change the {@link BytesRef#bytes bytes reference} of the {@link BytesRef}
* to point to an internal structure or modify the content of the {@link BytesRef} but should
* always do it in a consistent way. For example, it is illegal to change the bytes content in
* some call and to change the reference to point to an internal structure in another call, this
* will lead to bugs. It is also illegal for callers to write into the {@link BytesRef#bytes bytes}
* after this method has returned.
*/
public abstract BytesRef getValueScratchByOrd(long ord, BytesRef ret);