How to use

PassageKeyFactory

in

org.crosswire.jsword.passage

public final Key getKey(String text) throws NoSuchKeyException {
  return PassageKeyFactory.instance().getKey(Versifications.instance().getVersification(versification), text);
}

  /**
   * Return a Key representing the passage passed in or an empty passage if it can't be parsed.
   * @param passage Textual ref
   * @return
   */
  public Key getKey(String passage) {
    Key key = null;
    try {
      // spaces confuse the osis parser
      passage = passage.trim();
      
      // If expecting OSIS then use OSIS parser
      key = osisParser.parseOsisRef(v11n, passage);
      
      // OSIS parser is strict so try treating as normal ref if osis parser fails
      if (key==null) {
        Log.d(TAG, "Non OSIS Reading plan passage:"+passage);
        key = PassageKeyFactory.instance().getKey(v11n, passage);
      }
    } catch (Exception e) {
      Log.e(TAG, "Invalid passage reference in reading plan:"+passage);
    }
    
    // If all else fails return an empty passage to prevent NPE
    if (key==null) {
      key = PassageKeyFactory.instance().createEmptyKeyList(v11n);
    }
    return key;
  }
}

private Key getReferenceKey() {
  Key key=null;
  try {
    if (noteType.equals(NoteType.TYPE_REFERENCE)) {
      String reference = StringUtils.isNotEmpty(osisRef) ? osisRef : noteText;
      key = PassageKeyFactory.instance().getValidKey(v11n, reference);
    }
  } catch (Exception e) {
    log.warn("Error getting note reference for osisRef "+osisRef, e);
  }
  return key;
}

/**
 * Convert the passageReference into a Passage or an empty Passage,
 * if there is an error. Note, this is not recommended as it throws
 * away the error.
 * 
 * @param v11n
 *            The Versification to which this Passage belongs.
 * @param passageReference
 *            A String containing the text of the Passage
 * @param basis
 *           The basis by which to interpret passageReference
 * @return a new Passage filled with the desired Verses or an empty Passage
 */
public Key getValidKey(Versification v11n, String passageReference, Key basis) {
  try {
    return getKey(v11n, passageReference, basis);
  } catch (NoSuchKeyException e) {
    return createEmptyKeyList(v11n);
  }
}

/**
 * Cast a Key to a Passage. Only those keys that are a Passage or can
 * be held by a Passage (i.e. Verse and VerseRange) may be cast to one.
 * If you pass a null key into this method, you get a null Passage out.
 * 
 * @param key The key to cast
 * @return The key cast to a Passage
 * @throws ClassCastException
 */
public static Passage getPassage(Key key) {
  if (key == null) {
    return null;
  }
  if (key instanceof Passage) {
    return (Passage) key;
  }
  if (key instanceof VerseKey) {
    VerseKey verseKey = (VerseKey) key;
    Key ref = PassageKeyFactory.instance().createEmptyKeyList(verseKey.getVersification());
    ref.addAll(verseKey);
    return (Passage) ref;
  }
  throw new ClassCastException("Expected key to be a Verse, VerseRange or Passage");
}

public final Key getGlobalKeyList() {
  if (global == null) {
    try {
      global = getBackend().getGlobalKeyList();
      return global;
    } catch (UnsupportedOperationException ex) {
      // fail silently, operation not supported by the backend
      log.debug(ex.getMessage());
    } catch (BookException ex) {
      // failing silently, as previous behavior was to attempt to
      // return as much as we can using the slower method
      log.debug(ex.getMessage());
    }
    Versification v11n = super.getVersification();
    global = super.createEmptyKeyList();
    Key all = PassageKeyFactory.instance().getGlobalKeyList(v11n);
    for (Key key : all) {
      if (contains(key)) {
        global.addAll(key);
      }
    }
  }
  return global;
}

/**
 * Convert the passageReference into a Passage. This is the recommended
 * form for application constructed references and user input. Both of
 * these should have a fully qualified first reference.
 * 
 * @param v11n
 *            The Versification to which this Passage belongs.
 * @param passageReference
 *            A String containing the text for the Passage
 * @return a new Passage filled with the desired Verses
 * @throws NoSuchKeyException
 *             If the passageReference has anything that could not be understood as a Verse
 */
public Passage getKey(Versification v11n, String passageReference) throws NoSuchKeyException {
  return getKey(v11n, passageReference, null);
}

/**
 * Construct an AbstractPassageBook given the BookMetaData and the AbstractBackend.
 *
 * @param bmd     the metadata that describes the book
 * @param backend the means by which the resource is accessed
 */
public AbstractPassageBook(BookMetaData bmd, Backend backend) {
  super(bmd, backend);
  keyf = PassageKeyFactory.instance();
  this.versification = bmd.getProperty(BookMetaData.KEY_VERSIFICATION);
}

Passage ref = (Passage) keyf.createEmptyKeyList(rs);
int type = fromBinary(buffer, index, AbstractPassage.METHOD_COUNT);
  int verses = fromBinary(buffer, index, maxOrdinal);
  for (int i = 0; i < verses; i++) {
    int ord = fromBinary(buffer, index, maxOrdinal);
    ref.add(rs.decodeOrdinal(ord));
  int ranges = fromBinary(buffer, index, maxOrdinal / 2);
  for (int i = 0; i < ranges; i++) {
    int ord = fromBinary(buffer, index, maxOrdinal);
    int len = fromBinary(buffer, index, maxOrdinal);
    ref.add(RestrictionType.NONE.toRange(rs, rs.decodeOrdinal(ord), len));

public final Key createEmptyKeyList() {
  return keyf.createEmptyKeyList(Versifications.instance().getVersification(versification));
}

/**
 * Set the default PassageType. Must be the ordinal value of one of:
 * <ul>
 * <li>PassageType.SPEED
 * <li>PassageType.WRITE_SPEED
 * <li>PassageType.SIZE
 * <li>PassageType.MIX
 * <li>PassageType.TALLY
 * </ul>
 * 
 * @param newDefaultType
 *            The new default type.
 */
public static void setDefaultPassage(int newDefaultType) {
  setDefaultType(PassageType.fromInteger(newDefaultType));
}

/**
 * Convert the passageReference into a Passage or an empty Passage,
 * if there is an error. Note, this is not recommended as it throws
 * away the error.
 * 
 * @param v11n
 *            The Versification to which this Passage belongs.
 * @param passageReference
 *            A String containing the text for the Passage
 * @return a new Passage filled with the desired Verses or an empty Passage
 */
public Key getValidKey(Versification v11n, String passageReference) {
  return getValidKey(v11n, passageReference, null);
}

int arraySize = binarySize(AbstractPassage.METHOD_COUNT) + (maxOrdinal / 8) + 1;
byte[] buffer = new byte[arraySize];
int index = 0;
index += toBinary(buffer, index, AbstractPassage.BITWISE, AbstractPassage.METHOD_COUNT);
int arraySize = binarySize(AbstractPassage.METHOD_COUNT) + binarySize(maxOrdinal)
    + (verses * binarySize(maxOrdinal));
byte[] buffer = new byte[arraySize];
int index = 0;
index += toBinary(buffer, index, AbstractPassage.DISTINCT, AbstractPassage.METHOD_COUNT);
index += toBinary(buffer, index, verses, maxOrdinal);
  Verse verse = (Verse) aKey;
  int ord = verse.getOrdinal();
  index += toBinary(buffer, index, ord, maxOrdinal);
int arraySize = binarySize(AbstractPassage.METHOD_COUNT) + binarySize(maxOrdinal / 2)
    + (2 * ranges * binarySize(maxOrdinal));
byte[] buffer = new byte[arraySize];
int index = 0;
index += toBinary(buffer, index, AbstractPassage.RANGED, AbstractPassage.METHOD_COUNT);
index += toBinary(buffer, index, ranges, maxOrdinal / 2);
while (it.hasNext()) {
  VerseRange range = it.next();
  index += toBinary(buffer, index, range.getStart().getOrdinal(), maxOrdinal);

/**
 * Convert the passageReference into a Passage. This is the recommended
 * form for understanding references in ThML and GBF.
 * 
 * @param v11n
 *            The Versification to which this Passage belongs.
 * @param passageReference
 *            A String containing the text for the Passage
 * @param basis
 *           The basis by which to interpret passageReference
 * @return a new Passage filled with the desired Verses
 * @throws NoSuchKeyException
 *             If the passageReference has anything that could not be understood as a Verse
 */
public Passage getKey(Versification v11n, String passageReference, Key basis) throws NoSuchKeyException {
  // since normalization is relatively expensive
  // don't try it unless it solves a problem.
  try {
    return defaultType.createPassage(v11n, passageReference, basis);
  } catch (NoSuchKeyException e) {
    try {
      return defaultType.createPassage(v11n, normalize(passageReference), basis);
    } catch (NoSuchKeyException ex) {
      // TODO(DM): Parser should allow valid osisRefs!
      return defaultType.createPassage(v11n, mungOsisRef(passageReference), basis);
    }
  }
}

/**
 * Flexible converter for the generic Key base class.  
 * Return the key in the required versification, mapping if necessary
 * Currently only handles Passage, RangedPassage, and Verse
 */
public Key convert(Key key, Versification toVersification) {
  try {
    if (key instanceof RangedPassage) {
      return convert((RangedPassage)key, toVersification);
    } else if (key instanceof VerseRange) {
      return convert((VerseRange)key, toVersification);
    } else if (key instanceof Passage) {
      return convert((Passage)key, toVersification);
    } else if (key instanceof Verse) {
      return convert((Verse)key, toVersification);
    }
  } catch (Exception e) {
    // unexpected problem during mapping
    Log.e(TAG, "JSword Versification mapper failed to map "+key.getOsisID()+" to "+toVersification.getName(), e);
  }
  return PassageKeyFactory.instance().createEmptyKeyList(toVersification);
}

/**
 * Read a passage from a given stream
 * 
 * @param in
 *            The stream to read from
 * @return a newly built Passage
 * @throws IOException
 *             If there was trouble reading the stream
 * @throws NoSuchKeyException
 *             if the data was not a valid passage
 */
public static Passage readPassage(Reader in) throws IOException, NoSuchKeyException {
  // Get any versification. It does not matter. readDescripton will overwrite it.
  Versification rs = Versifications.instance().getVersification("KJV");
  Passage ref = (Passage) keyf.createEmptyKeyList(rs);
  ref.readDescription(in);
  return ref;
}

PassageKeyFactory.setDefaultType(PassageType.MIX);

  result.append("</a>");
} else {
  Passage ref = (Passage) PassageKeyFactory.instance().getKey(parameters.getDocumentVersification(), reference);
  boolean isSingleVerse = ref.countVerses()==1;
  boolean hasContent = content.length()>0;

/**
 * A space separate string containing osisID from the reference element.
 * We pass book and key because the xref may not be valid and it needs to be reported.
 *
 * @param book the book to which the references refer
 * @param key the verse containing the cross references
 * @param v11n the versification
 * @param root the osis element in question
 * @return The references in the text
 */
public static String getReferences(Book book, Key key, Versification v11n, Element root) {
  PassageKeyFactory keyf = PassageKeyFactory.instance();
  Key collector = keyf.createEmptyKeyList(v11n);
  for (Content content : getDeepContent(root, OSISUtil.OSIS_ELEMENT_REFERENCE)) {
    Element ele = (Element) content;
    String attr = ele.getAttributeValue(OSISUtil.OSIS_ATTR_REF);
    if (attr != null) {
      try {
        collector.addAll(keyf.getKey(v11n, attr));
      } catch (NoSuchKeyException e) {
        DataPolice.report(book, key, "Unable to parse: " + attr + " - No such reference:" + e.getMessage());
      }
    }
  }
  return collector.getOsisID();
}

  @Override
  public void processContent(Book book, Key key, Element ele) {
    String refstr = ele.getValue();
    try {
      if (ele.getAttribute(OSISUtil.OSIS_ATTR_REF) == null) {
        Passage ref = PassageKeyFactory.instance().getKey(KeyUtil.getVersification(key), refstr, key);
        String osisname = ref.getOsisRef();
        ele.setAttribute(OSISUtil.OSIS_ATTR_REF, osisname);
      }
    } catch (NoSuchKeyException ex) {
      DataPolice.report(book, key, "scripRef has no passage attribute, unable to guess: (" + refstr + ") due to " + ex.getMessage());
    }
  }
}