segment.java

HTML解析器是一个Java库

	 * Specifying a <code>null</code> argument to the <code>name</code> parameter is equivalent to {@link #getAllStartTags()}.
	 * <p>
	 * This method also returns {@linkplain Tag#isUnregistered() unregistered} tags if the specified name is not a valid {@linkplain Tag#isXMLName(CharSequence) XML tag name}.
	 *
	 * @param name  the {@linkplain StartTag#getName() name} of the start tags to get.
	 * @return a list of all {@linkplain StartTagType#NORMAL normal} {@link StartTag} objects with the specified {@linkplain StartTag#getName() name} that are {@linkplain #encloses(Segment) enclosed} by this segment.
	 */
	public List<StartTag> getAllStartTags(String name) {
		if (name!=null) name=name.toLowerCase();
		final boolean isXMLTagName=Tag.isXMLName(name);
		StartTag startTag=(StartTag)checkEnclosure(StartTag.getNext(source,begin,name,StartTagType.NORMAL,isXMLTagName));
		if (startTag==null) return Collections.emptyList();
		final ArrayList<StartTag> list=new ArrayList<StartTag>();
		do {
			list.add(startTag);
			startTag=(StartTag)checkEnclosure(StartTag.getNext(source,startTag.begin+1,name,StartTagType.NORMAL,isXMLTagName));
		} while (startTag!=null);
		return list;
	}

	/**
	 * Returns a list of all {@link StartTag} objects with the specified attribute name/value pair 
	 * that are {@linkplain #encloses(Segment) enclosed} by this segment.
	 * <p>
	 * See the {@link Tag} class documentation for more details about the behaviour of this method.
	 *
	 * @param attributeName  the attribute name (case insensitive) to search for, must not be <code>null</code>.
	 * @param value  the value of the specified attribute to search for, must not be <code>null</code>.
	 * @param valueCaseSensitive  specifies whether the attribute value matching is case sensitive.
	 * @return a list of all {@link StartTag} objects with the specified attribute name/value pair that are {@linkplain #encloses(Segment) enclosed} by this segment.
	 */
	public List<StartTag> getAllStartTags(final String attributeName, final String value, final boolean valueCaseSensitive) {
		StartTag startTag=(StartTag)checkEnclosure(source.getNextStartTag(begin,attributeName,value,valueCaseSensitive));
		if (startTag==null) return Collections.emptyList();
		final ArrayList<StartTag> list=new ArrayList<StartTag>();
		do {
			list.add(startTag);
			startTag=(StartTag)checkEnclosure(source.getNextStartTag(startTag.begin+1,attributeName,value,valueCaseSensitive));
		} while (startTag!=null);
		return list;
	}

	/**
	 * Returns a list of the immediate children of this segment in the document element hierarchy.
	 * <p>
	 * The returned list may include an element that extends beyond the end of this segment, as long as it begins within this segment.
	 * <p>
	 * An element found at the start of this segment is included in the list.
	 * Note however that if this segment <i>is</i> an {@link Element}, the overriding {@link Element#getChildElements()} method is called instead,
	 * which only returns the children of the element.
	 * <p>
	 * Calling <code>getChildElements()</code> on an <code>Element</code> is much more efficient than calling it on a <code>Segment</code>.
	 * <p>
	 * The objects in the list are all of type {@link Element}.
	 * <p>
	 * The {@link Source#fullSequentialParse()} method should be called after construction of the {@link Source} object
	 * if this method is to be used on a large proportion of the source.
	 * It is called automatically if this method is called on the {@link Source} object itself.
	 * <p>
	 * See the {@link Source#getChildElements()} method for more details.
	 *
	 * @return the a list of the immediate children of this segment in the document element hierarchy, guaranteed not <code>null</code>.
	 * @see Element#getParentElement()
	 */
	public List<Element> getChildElements() {
		if (length()==0) return Collections.emptyList();
		List<Element> childElements=new ArrayList<Element>();
		int pos=begin;
		while (true) {
			final StartTag childStartTag=source.getNextStartTag(pos);
			if (childStartTag==null || childStartTag.begin>=end) break;
			if (!Config.IncludeServerTagsInElementHierarchy && childStartTag.getTagType().isServerTag()) {
				pos=childStartTag.end;
				continue;
			}
			final Element childElement=childStartTag.getElement();
			childElements.add(childElement);
			childElement.getChildElements();
			pos=childElement.end;
		}
		return childElements;
	}

	/**
	 * Returns a list of all {@link Element} objects that are {@linkplain #encloses(Segment) enclosed} by this segment.
	 * <p>
	 * The {@link Source#fullSequentialParse()} method should be called after construction of the {@link Source} object
	 * if this method is to be used on a large proportion of the source.
	 * It is called automatically if this method is called on the {@link Source} object itself.
	 * <p>
	 * The elements returned correspond exactly with the start tags returned in the {@link #getAllStartTags()} method.
	 * <p>
	 * If this segment is itself an {@link Element}, the result includes this element in the list.
	 *
	 * @return a list of all {@link Element} objects that are {@linkplain #encloses(Segment) enclosed} by this segment.
	 */
	public List<Element> getAllElements() {
		return getAllElements((String)null);
	}

	/**
	 * Returns a list of all {@link Element} objects with the specified name that are {@linkplain #encloses(Segment) enclosed} by this segment.
	 * <p>
	 * The elements returned correspond exactly with the start tags returned in the {@link #getAllStartTags(String name)} method.
	 * <p>
	 * Specifying a <code>null</code> argument to the <code>name</code> parameter is equivalent to {@link #getAllElements()}.
	 * <p>
	 * This method also returns elements consisting of {@linkplain Tag#isUnregistered() unregistered} tags if the specified name is not a valid {@linkplain Tag#isXMLName(CharSequence) XML tag name}.
	 * <p>
	 * If this segment is itself an {@link Element} with the specified name, the result includes this element in the list.
	 *
	 * @param name  the {@linkplain Element#getName() name} of the elements to get.
	 * @return a list of all {@link Element} objects with the specified name that are {@linkplain #encloses(Segment) enclosed} by this segment.
	 */
	public List<Element> getAllElements(String name) {
		if (name!=null) name=name.toLowerCase();
		final List<StartTag> startTags=getAllStartTags(name);
		if (startTags.isEmpty()) return Collections.emptyList();
		final ArrayList<Element> elements=new ArrayList<Element>(startTags.size());
		for (StartTag startTag : startTags) {
			final Element element=startTag.getElement();
			if (element.end>end) break;
			elements.add(element);
		}
		return elements;
	}

	/**
	 * Returns a list of all {@link Element} objects with start tags of the specified {@linkplain StartTagType type} that are {@linkplain #encloses(Segment) enclosed} by this segment.
	 * <p>
	 * The elements returned correspond exactly with the start tags returned in the {@link #getAllTags(TagType)} method.
	 * <p>
	 * If this segment is itself an {@link Element} with the specified type, the result includes this element in the list.
	 *
	 * @param startTagType  the {@linkplain StartTagType type} of start tags to get, must not be <code>null</code>.
	 * @return a list of all {@link Element} objects with start tags of the specified {@linkplain StartTagType type} that are {@linkplain #encloses(Segment) enclosed} by this segment.
	 */
	public List<Element> getAllElements(final StartTagType startTagType) {
		final List<StartTag> startTags=getAllStartTags(startTagType);
		if (startTags.isEmpty()) return Collections.emptyList();
		final ArrayList<Element> elements=new ArrayList<Element>(startTags.size());
		for (StartTag startTag : startTags) {
			final Element element=startTag.getElement();
			if (element.end>end) break;
			elements.add(element);
		}
		return elements;
	}

	/**
	 * Returns a list of all {@link Element} objects with the specified attribute name/value pair 
	 * that are {@linkplain #encloses(Segment) enclosed} by this segment.
	 * <p>
	 * The elements returned correspond exactly with the start tags returned in the {@link #getAllStartTags(String attributeName, String value, boolean valueCaseSensitive)} method.
	 * <p>
	 * If this segment is itself an {@link Element} with the specified name/value pair, the result includes this element in the list.
	 *
	 * @param attributeName  the attribute name (case insensitive) to search for, must not be <code>null</code>.
	 * @param value  the value of the specified attribute to search for, must not be <code>null</code>.
	 * @param valueCaseSensitive  specifies whether the attribute value matching is case sensitive.
	 * @return a list of all {@link Element} objects with the specified attribute name/value pair that are {@linkplain #encloses(Segment) enclosed} by this segment.
	 */
	public List<Element> getAllElements(final String attributeName, final String value, final boolean valueCaseSensitive) {
		final List<StartTag> startTags=getAllStartTags(attributeName,value,valueCaseSensitive);
		if (startTags.isEmpty()) return Collections.emptyList();
		final ArrayList<Element> elements=new ArrayList<Element>(startTags.size());
		for (StartTag startTag : startTags) {
			final Element element=startTag.getElement();
			if (element.end>end) break;
			elements.add(element);
		}
		return elements;
	}

	/**
	 * Returns a list of all {@link CharacterReference} objects that are {@linkplain #encloses(Segment) enclosed} by this segment.
	 * @return a list of all {@link CharacterReference} objects that are {@linkplain #encloses(Segment) enclosed} by this segment.
	 */
	public List<CharacterReference> getAllCharacterReferences() {
		CharacterReference characterReference=getNextCharacterReference(begin);
		if (characterReference==null) return Collections.emptyList();
		final ArrayList<CharacterReference> list=new ArrayList<CharacterReference>();
		do {
			list.add(characterReference);
			characterReference=getNextCharacterReference(characterReference.end);
		} while (characterReference!=null);
		return list;
	}

	/**
	 * Returns the first {@link StartTag} {@linkplain #encloses(Segment) enclosed} by this segment.
	 * <p>
	 * This is equivalent to {@link #getSource()}<code>.</code>{@link Source#getNextStartTag(int) getNextStartTag}<code>(</code>{@link #getBegin()}<code>)</code>.
	 *
	 * @return the first {@link StartTag} {@linkplain #encloses(Segment) enclosed} by this segment, or <code>null</code> if none exists.
	 */
	public StartTag getFirstStartTag() {
		return source.getNextStartTag(begin);
	}
	
	/**
	 * Returns the first {@link StartTag} of the specified {@linkplain StartTagType type} {@linkplain #encloses(Segment) enclosed} by this segment.
	 * <p>
	 * This is equivalent to {@link #getSource()}<code>.</code>{@link Source#getNextStartTag(int,StartTagType) getNextStartTag}<code>(</code>{@link #getBegin()}<code>,startTagType)</code>.
	 *
	 * @param startTagType  the <code>StartTagType</code> to search for.
	 * @return the first {@link StartTag} of the specified {@linkplain StartTagType type} {@linkplain #encloses(Segment) enclosed} by this segment, or <code>null</code> if none exists.
	 */
	public StartTag getFirstStartTag(StartTagType startTagType) {
		return source.getNextStartTag(begin,startTagType);
	}
	
	/**
	 * Returns the first {@linkplain StartTagType#NORMAL normal} {@link StartTag} {@linkplain #encloses(Segment) enclosed} by this segment.
	 * <p>
	 * This is equivalent to {@link #getSource()}<code>.</code>{@link Source#getNextStartTag(int,String) getNextStartTag}<code>(</code>{@link #getBegin()}<code>,name)</code>.
	 * <p>
	 * Specifying a <code>null</code> argument to the <code>name</code> parameter is equivalent to {@link #getFirstStartTag()}.
	 *
	 * @param name  the {@linkplain StartTag#getName() name} of the start tag to search for, may be <code>null</code>.
	 * @return the first {@linkplain StartTagType#NORMAL normal} {@link StartTag} {@linkplain #encloses(Segment) enclosed} by this segment, or <code>null</code> if none exists.
	 */
	public StartTag getFirstStartTag(String name) {
		return source.getNextStartTag(begin,name);
	}
	
	/**
	 * Returns the first {@link StartTag} with the specified attribute name/value pair {@linkplain #encloses(Segment) enclosed} by this segment.
	 * <p>
	 * This is equivalent to {@link #getSource()}<code>.</code>{@link Source#getNextStartTag(int,String,String,boolean) getNextStartTag}<code>(</code>{@link #getBegin()}<code>,attributeName,value,valueCaseSensitive)</code>.
	 *
	 * @param attributeName  the attribute name (case insensitive) to search for, must not be <code>null</code>.
	 * @param value  the value of the specified attribute to search for, must not be <code>null</code>.
	 * @param valueCaseSensitive  specifies whether the attribute value matching is case sensitive.
	 * @return the first {@link StartTag} with the specified attribute name/value pair {@linkplain #encloses(Segment) enclosed} by this segment, or <code>null</code> if none exists.
	 */
	public StartTag getFirstStartTag(String attributeName, String value, boolean valueCaseSensitive) {
		return source.getNextStartTag(begin,attributeName,value,valueCaseSensitive);
	}
	
	/**
	 * Returns the first {@link Element} {@linkplain #encloses(Segment) enclosed} by this segment.
	 * <p>
	 * This is equivalent to {@link #getSource()}<code>.</code>{@link Source#getNextElement(int) getNextElement}<code>(</code>{@link #getBegin()}<code>)</code>.
	 * <p>
	 * If this segment is itself an {@link Element}, this element is returned, not the first child element.
	 *
	 * @return the first {@link Element} {@linkplain #encloses(Segment) enclosed} by this segment, or <code>null</code> if none exists.
	 */
	public Element getFirstElement() {
		return source.getNextElement(begin);
	}
	
	/**
	 * Returns the first {@linkplain StartTagType#NORMAL normal} {@link Element} with the specified {@linkplain Element#getName() name} {@linkplain #encloses(Segment) enclosed} by this segment.
	 * <p>
	 * This is equivalent to {@link #getSource()}<code>.</code>{@link Source#getNextElement(int,String) getNextElement}<code>(</code>{@link #getBegin()}<code>,name)</code>.
	 * <p>
	 * Specifying a <code>null</code> argument to the <code>name</code> parameter is equivalent to {@link #getFirstElement()}.
	 * <p>
	 * If this segment is itself an {@link Element} with the specified name, this element is returned.
	 *
	 * @param name  the {@linkplain Element#getName() name} of the element to search for.
	 * @return the first {@linkplain StartTagType#NORMAL normal} {@link Element} with the specified {@linkplain Element#getName() name} {@linkplain #encloses(Segment) enclosed} by this segment, or <code>null</code> if none exists.
	 */
	public Element getFirstElement(String name) {
		return source.getNextElement(begin,name);
	}
	
	/**
	 * Returns the first {@link Element} with the specified attribute name/value pair {@linkplain #encloses(Segment) enclosed} by this segment.
	 * <p>
	 * This is equivalent to {@link #getSource()}<code>.</code>{@link Source#getNextElement(int,String,String,boolean) getNextElement}<code>(</code>{@link #getBegin()}<code>,attributeName,value,valueCaseSensitive)</code>.
	 * <p>
	 * If this segment is itself an {@link Element} with the specified attribute name/value pair, this element is returned.
	 *
	 * @param attributeName  the attribute name (case insensitive) to search for, must not be <code>null</code>.
	 * @param value  the value of the specified attribute to search for, must not be <code>null</code>.
	 * @param valueCaseSensitive  specifies whether the attribute value matching is case sensitive.
	 * @return the first {@link Element} with the specified attribute name/value pair {@linkplain #encloses(Segment) enclosed} by this segment, or <code>null</code> if none exists.
	 */
	public Element getFirstElement(String attributeName, String value, boolean valueCaseSensitive) {
		return source.getNextElement(begin,attributeName,value,valueCaseSensitive);
	}

	/**
	 * Returns a list of the {@link FormControl} objects that are {@linkplain #encloses(Segment) enclosed} by this segment.
	 * @return a list of the {@link FormControl} objects that are {@linkplain #encloses(Segment) enclosed} by this segment.
	 */
	public List<FormControl> getFormControls() {
		return FormControl.getAll(this);
	}

	/**
	 * Returns the {@link FormFields} object representing all form fields that are {@linkplain #encloses(Segment) enclosed} by this segment.
	 * <p>
	 * This is equivalent to {@link FormFields#FormFields(Collection) new FormFields}<code>(</code>{@link #getFormControls()}<code>)</code>.
	 *
	 * @return the {@link FormFields} object representing all form fields that are {@linkplain #encloses(Segment) enclosed} by this segment.
	 * @see #getFormControls()
	 */
	public FormFields getFormFields() {
		return new FormFields(getFormControls());
	}

	/**
	 * Parses any {@link Attributes} within this segment.
	 * This method is only used in the unusual situation where attributes exist outside of a start tag.
	 * The {@link StartTag#getAttributes()} method should be used in normal situations.
	 * <p>
	 * This is equivalent to <code>source.</code>{@link Source#parseAttributes(int,int) parseAttributes}<code>(</code>{@link #getBegin()}<code>,</code>{@link #getEnd()}<code>)</code>.
	 *
	 * @return the {@link Attributes} within this segment, or <code>null</code> if too many errors occur while parsing.