javax.xml.parsers
클래스 DocumentBuilderFactory

java.lang.Object 
  javax.xml.parsers.DocumentBuilderFactory

public abstract class DocumentBuilderFactory
extends Object 

어플리케이션으로 XML 문서로부터 DOM 객체 트리를 생성하는 퍼서를 취득할 수 있는 팩토리 API 를 정의합니다.

생성자 의 개요

protected

DocumentBuilderFactory () 인스턴스화를 방해하는 protected 생성자 입니다.

메소드의 개요

abstract Object	getAttribute (String name) 사용자가 기본이 되는 구현의 특정의 속성을 꺼낼 수가 있도록(듯이) 합니다.
abstract boolean	getFeature (String name) 이름을 붙일 수 있었던 기능 상태를 가져옵니다.
Schema	getSchema () setSchema(Schema schema) 메소드를 개입시켜 지정된 Schema 객체를 가져옵니다.
boolean	isCoalescing () CDATA 노드를 Text 노드로 변환해, 그것을 인접 (존재하는 경우) Text 노드에 추가하는 퍼서를 작성하도록(듯이) 팩토리가 설정되어 있는지 어떤지를 나타냅니다.
boolean	isExpandEntityReferences () 엔티티 참조 노드를 전개하는 퍼서를 작성하도록(듯이) 팩토리가 설정되어 있는지 어떤지를 나타냅니다.
boolean	isIgnoringComments () 코멘트를 무시하는 퍼서를 작성하도록(듯이) 팩토리가 설정되어 있는지 어떤지를 나타냅니다.
boolean	isIgnoringElementContentWhitespace () 요소의 내용의 무시할 수 있는 공백을 무시하는 퍼서를 작성하도록(듯이) 팩토리가 설정되어 있는지 어떤지를 나타냅니다.
boolean	isNamespaceAware () 팩토리가 이름 공간을 인식하는 퍼서를 작성하도록(듯이) 설정되어 있는지 어떤지를 나타냅니다.
boolean	isValidating () 구문 분석시에 XML 컨텐츠를 검증하는 퍼서를 작성하도록(듯이) 팩토리가 설정되어 있는지 어떤지를 나타냅니다.
boolean	isXIncludeAware () XInclude 처리 상태를 가져옵니다.
abstract DocumentBuilder	newDocumentBuilder () 현재 설정되어 있는 파라미터를 사용해 DocumentBuilder 의 새로운 인스턴스를 작성합니다.
static DocumentBuilderFactory	newInstance () DocumentBuilderFactory 의 새로운 인스턴스를 가져옵니다.
static DocumentBuilderFactory	newInstance (String factoryClassName, ClassLoader classLoader) DocumentBuilderFactory 의 새로운 인스턴스를 클래스명으로부터 가져옵니다.
abstract void	setAttribute (String name, Object value) 사용자가 기본이 되는 구현에 특정의 속성을 설정할 수 있도록(듯이) 합니다.
void	setCoalescing (boolean coalescing) 이 팩토리로 작성된 퍼서가 CDATA 노드를 Text 노드로 변환해, 그것을 인접 (존재하는 경우) Text 노드에 추가하도록(듯이) 지정합니다.
void	setExpandEntityReferences (boolean expandEntityRef) 이 팩토리로 작성된 퍼서가 엔티티 참조 노드를 전개하도록(듯이) 지정합니다.
abstract void	setFeature (String name, boolean value) 이 팩토리에 의해 생성된 DocumentBuilderFactory 및 DocumentBuilder 의 기능을 설정합니다.
void	setIgnoringComments (boolean ignoreComments) 이 코드로 작성된 퍼서가 코멘트를 무시하도록(듯이) 지정합니다.
void	setIgnoringElementContentWhitespace (boolean whitespace) 이 팩토리로 작성된 퍼서가, XML 문서의 구문 분석시에 요소의 내용의 공백 (대략적으로 「무시할 수 있는 공백」이라고 불리는 일이 있다)을 배제하도록(듯이) 지정합니다 (XML Rec 2.10 을 참조).
void	setNamespaceAware (boolean awareness) 이 팩토리로 작성된 퍼서가 XML 이름 공간을 지원하도록(듯이) 지정합니다.
void	setSchema (Schema schema) 이 팩토리로부터 작성된 퍼서에 의해 사용되는 Schema 를 설정합니다.
void	setValidating (boolean validating) 이 팩토리로 작성된 퍼서가 구문 분석시에 문서의 타당성을 검증하도록(듯이) 지정합니다.
void	setXIncludeAware (boolean state) XInclude 처리 상태를 설정합니다.

클래스 java.lang. Object 로부터 상속된 메소드

clone , equals , finalize , getClass , hashCode , notify , notifyAll , toString , wait , wait , wait

생성자 의 상세

DocumentBuilderFactory

protected DocumentBuilderFactory()

인스턴스화를 방해하는 protected 생성자 입니다. newInstance() 를 사용합니다.

메소드의 상세

newInstance

public static DocumentBuilderFactory  newInstance()

DocumentBuilderFactory 의 새로운 인스턴스를 가져옵니다. 이 static 메소드는 새로운 팩토리 인스턴스를 작성합니다. 이 메소드는 다음의 순서의 검색 순서로, 로드하는 DocumentBuilderFactory 구현 클래스를 결정합니다.

• javax.xml.parsers.DocumentBuilderFactory 시스템 프로퍼티을 사용한다
• JRE 디렉토리내의 프로퍼티 파일 lib/jaxp.properties 를 사용한다. 이 구성 파일은 표준의 java.util.Properties 형식이며, 상기와 같이 정의된 시스템 프로퍼티인 키를 가지는 구현 클래스의 완전 지정의 이름을 포함한다. jaxp.properties 파일은 JAXP 구현에 의해 1 회만 읽혀 그 값이 그 후의 사용을 위해 캐쉬된다. 최초의 read시에 파일이 존재하지 않으면 그 후에 그 존재가 체크될 것은 없다. 최초로 읽힌 뒤, jaxp.properties 의 프로퍼티의 값을 변경할 수 없다.
• 가능하면, JAR 스펙으로 상세하게 설명되고 있는 서비스 API 를 사용해, 클래스명을 판정한다. Services API 는, 실행시에 사용할 수 있는 jar 내의 META-INF/services/javax.xml.parsers.DocumentBuilderFactory 파일로부터 클래스명을 검색한다
• 플랫폼의 디폴트의 DocumentBuilderFactory 인스턴스

어플리케이션이 DocumentBuilderFactory 에의 참조를 취득하면(자), 팩토리를 사용해 퍼서의 인스턴스를 설정 및 취득할 수가 있습니다.

트러블 슈팅의 힌트

　

jaxp.debug 시스템 프로퍼티을 설정하면(자), 이 메소드는 실행중의 처리나 검색하고 있는 장소에 관한 대량의 디버그 메세지를 System.err 에 출력합니다.

　

DocumentBuilder 의 로드에 문제가 있는 경우, 다음과 같이 합니다.

 java -Djaxp.debug=1 YourProgram ....
 

반환값:

DocumentBuilderFactory 의 새로운 인스턴스

예외:

FactoryConfigurationError - 구현을 사용할 수 없는가 인스턴스화할 수 없는 경우

newInstance

public static DocumentBuilderFactory  newInstance(String  factoryClassName,
                                                 ClassLoader  classLoader)

DocumentBuilderFactory 의 새로운 인스턴스를 클래스명으로부터 가져옵니다. 이 함수는, 클래스 패스에 복수의 프로바이더가 있는 경우에 편리합니다. 어느 프로바이더가 로드 되는지를 지정할 수 있기 (위해)때문에, 어플리케이션을 한층 더 제어할 수 있습니다.

　

어플리케이션이 DocumentBuilderFactory 에의 참조를 취득하면(자), 팩토리를 사용해 퍼서의 인스턴스를 설정 및 취득할 수가 있습니다.

트러블 슈팅의 힌트

　

jaxp.debug 시스템 프로퍼티을 설정하면(자), 이 메소드는 실행중의 처리나 검색하고 있는 장소에 관한 대량의 디버그 메세지를 System.err 에 출력합니다.

　

문제가 있는 경우, 다음과 같이 합니다.

 java -Djaxp.debug=1 YourProgram ....
 

파라미터:

factoryClassName - javax.xml.parsers.DocumentBuilderFactory 의 구현을 제공하는, 완전 수식의 팩토리 클래스명입니다.

classLoader - 팩토리 클래스의 로드에 사용되는 ClassLoader. null 의 경우는 현재의 Thread 의 문맥 classLoader 가, 팩토리 클래스의 로드에 사용됩니다.

반환값:

DocumentBuilderFactory 의 새로운 인스턴스

예외:

FactoryConfigurationError - factoryClassName 가 null, 또는, 팩토리 클래스가 로드, 인스턴스화할 수 없는 경우.

도입된 버젼:

1.6

관련 항목:

newInstance()

newDocumentBuilder

public abstract DocumentBuilder  newDocumentBuilder()
                                            throws ParserConfigurationException 

현재 설정되어 있는 파라미터를 사용해 DocumentBuilder 의 새로운 인스턴스를 작성합니다.

반환값:

DocumentBuilder 의 새로운 인스턴스

예외:

ParserConfigurationException - 요구된 구성을 채우는 DocumentBuilder (을)를 생성할 수 없는 경우

setNamespaceAware

public void setNamespaceAware(boolean awareness)

이 팩토리로 작성된 퍼서가 XML 이름 공간을 지원하도록(듯이) 지정합니다. 디폴트에서는, 이 값은 false 로 설정됩니다.

파라미터:

awareness - 작성된 퍼서가 XML 이름 공간을 지원하는 경우는 true, 그렇지 않은 경우는 false

setValidating

public void setValidating(boolean validating)

이 팩토리로 작성된 퍼서가 구문 분석시에 문서의 타당성을 검증하도록(듯이) 지정합니다. 디폴트에서는, 이 값은 false 로 설정됩니다.

여기서 말하는 「검증」이란, XML 권고로 정의되고 있는타당성을 검증하는 퍼서라고 하는 의미입니다. 즉, 실질적으로는 DTD 검증을 제어할 뿐(만큼)이라고 하는 것입니다. 다만, JAXP 1.2 에 정의되고 있는 종래의 2 개의 프로퍼티을 제외합니다.

DTD 는 아니고, W3C XML Schema 또는 RELAX NG 등이 새로운 schema 언어를 사용하는 경우는,setValidating(boolean) 메소드를 false 로 해 퍼서를 타당성을 검증하지 않는 설정으로 하고 나서,setSchema(Schema) 메소드로 schema를 퍼서에게 관련짓습니다.

파라미터:

validating - 작성된 퍼서가 구문 분석시에 문서의 타당성을 검증하는 경우는 true, 그렇지 않은 경우는 false

setIgnoringElementContentWhitespace

public void setIgnoringElementContentWhitespace(boolean whitespace)

이 팩토리로 작성된 퍼서가, XML 문서의 구문 분석시에 요소의 내용의 공백 (대략적으로 「무시할 수 있는 공백」이라고 불리는 일이 있다)을 배제하도록(듯이) 지정합니다 (XML Rec 2.10 을 참조). 요소만의 컨텐츠 모델 (XML Rec 3.2. 1 을 참조)를 가지는 요소의 내용에 직접 포함되는 공백만이 배제됩니다. 컨텐츠 모델에 의존하고 있기 위해서(때문에), 이 설정에서는 퍼서가 검증 모드인 것이 필요합니다. 디폴트에서는, 이 값은 false 로 설정됩니다.

파라미터:

whitespace - 작성된 퍼서가 XML 문서의 구문 분석시에 요소의 내용의 공백을 배제할 필요가 있는 경우는 true, 그렇지 않은 경우는 false

setExpandEntityReferences

public void setExpandEntityReferences(boolean expandEntityRef)

이 팩토리로 작성된 퍼서가 엔티티 참조 노드를 전개하도록(듯이) 지정합니다. 디폴트에서는, 이 값은 true 로 설정됩니다.

파라미터:

expandEntityRef - 작성된 퍼서가 엔티티 참조 노드를 전개하는 경우는 true, 그렇지 않은 경우는 false

setIgnoringComments

public void setIgnoringComments(boolean ignoreComments)

이 코드로 작성된 퍼서가 코멘트를 무시하도록(듯이) 지정합니다. 디폴트에서는, 이 값은 false 로 설정됩니다.

파라미터:

ignoreComments - 처리시에 코멘트를 무시하는 boolean 치

setCoalescing

public void setCoalescing(boolean coalescing)

이 팩토리로 작성된 퍼서가 CDATA 노드를 Text 노드로 변환해, 그것을 인접 (존재하는 경우) Text 노드에 추가하도록(듯이) 지정합니다. 디폴트에서는, 이 값은 false 로 설정됩니다.

파라미터:

coalescing - 작성된 퍼서가 CDATA 노드를 Text 노드로 변환해, 그것을 인접 (존재하는 경우) Text 노드에 추가하는 경우는 true, 그렇지 않은 경우는 false

isNamespaceAware

public boolean isNamespaceAware()

팩토리가 이름 공간을 인식하는 퍼서를 작성하도록(듯이) 설정되어 있는지 어떤지를 나타냅니다.

반환값:

팩토리가 이름 공간을 인식하는 퍼서를 작성하도록(듯이) 설정되어 있는 경우는 true, 그렇지 않은 경우는 false

isValidating

public boolean isValidating()

구문 분석시에 XML 컨텐츠를 검증하는 퍼서를 작성하도록(듯이) 팩토리가 설정되어 있는지 어떤지를 나타냅니다.

반환값:

구문 분석시에 XML 컨텐츠를 검증하는 퍼서를 작성하도록(듯이) 팩토리가 설정되어 있는 경우는 true, 그렇지 않은 경우는 false

isIgnoringElementContentWhitespace

public boolean isIgnoringElementContentWhitespace()

요소의 내용의 무시할 수 있는 공백을 무시하는 퍼서를 작성하도록(듯이) 팩토리가 설정되어 있는지 어떤지를 나타냅니다.

반환값:

요소의 내용의 무시할 수 있는 공백을 무시하는 퍼서를 작성하도록(듯이) 팩토리가 설정되어 있는 경우는 true, 그렇지 않은 경우는 false

isExpandEntityReferences

public boolean isExpandEntityReferences()

엔티티 참조 노드를 전개하는 퍼서를 작성하도록(듯이) 팩토리가 설정되어 있는지 어떤지를 나타냅니다.

반환값:

엔티티 참조 노드를 전개하는 퍼서를 작성하도록(듯이) 팩토리가 설정되어 있는 경우는 true, 그렇지 않은 경우는 false

isIgnoringComments

public boolean isIgnoringComments()

코멘트를 무시하는 퍼서를 작성하도록(듯이) 팩토리가 설정되어 있는지 어떤지를 나타냅니다.

반환값:

코멘트를 무시하는 퍼서를 작성하도록(듯이) 팩토리가 설정되어 있는 경우는 true, 그렇지 않은 경우는 false

isCoalescing

public boolean isCoalescing()

CDATA 노드를 Text 노드로 변환해, 그것을 인접 (존재하는 경우) Text 노드에 추가하는 퍼서를 작성하도록(듯이) 팩토리가 설정되어 있는지 어떤지를 나타냅니다.

반환값:

CDATA 노드를 Text 노드로 변환해, 그것을 인접 (존재하는 경우) Text 노드에 추가한다 퍼서를 작성하도록(듯이) 팩토리가 설정되어 있는 경우는 true, 그렇지 않은 경우는 false

setAttribute

public abstract void setAttribute(String  name,
                                  Object  value)
                           throws IllegalArgumentException 

사용자가 기본이 되는 구현에 특정의 속성을 설정할 수 있도록(듯이) 합니다.

파라미터:

name - 속성의 이름

value - 속성의 값

예외:

IllegalArgumentException - 기본이 되는 구현이 속성을 인식하지 않는 경우에 throw 된다

getAttribute

public abstract Object  getAttribute(String  name)
                             throws IllegalArgumentException 

사용자가 기본이 되는 구현의 특정의 속성을 꺼낼 수가 있도록(듯이) 합니다.

파라미터:

name - 속성의 이름

반환값:

속성의 값

예외:

IllegalArgumentException - 기본이 되는 구현이 속성을 인식하지 않는 경우에 throw 된다

setFeature

public abstract void setFeature(String  name,
                                boolean value)
                         throws ParserConfigurationException 

이 팩토리에 의해 생성된 DocumentBuilderFactory 및 DocumentBuilder 의 기능을 설정합니다.

기능명은 완전 수식 URI 입니다. 구현이 독자적인 기능을 정의할 수도 있습니다. 생성하는 DocumentBuilderFactory 또는 DocumentBuilder 가 그 기능을 지원할 수 없는 경우는,ParserConfigurationException 가 throw 됩니다. DocumentBuilderFactory 는 기능의 값을 표시할 수 있습니다만, 그 상태를 변경할 수 없습니다.

구현은 모두,XMLConstants.FEATURE_SECURE_PROCESSING 기능을 지원하고 있을 필요가 있습니다. 이 기능에 대해서는 다음과 같습니다.

• true. true 의 경우, 구현은 구현 한계에 준거하는 XML 처리를 제한합니다. 예는, 엔티티 확장 제한이나 대용량의 자원을 소비하는 XML schema 등. 시큐리티상의 이유로부터 XML 처리가 제한되는 경우는, 등록을 마친 ErrorHandler.fatalError(SAXParseException exception) 에 호출을 개입시켜 보고된다. DocumentBuilder.setErrorHandler(org.xml.sax.ErrorHandler errorHandler) 를 참조
• 기능이 false 의 경우, 구현은, 구현 한계에 상관하지 않고, XML 스펙에 따라 XML 를 처리한다

파라미터:

name - 기능명

value - 기능 상태가 true 인가 false 인가

예외:

ParserConfigurationException - 작성하는 DocumentBuilderFactory 또는 DocumentBuilder 하지만 이 기능을 지원할 수 없는 경우

NullPointerException - name 파라미터가 null 의 경우

getFeature

public abstract boolean getFeature(String  name)
                            throws ParserConfigurationException 

이름을 붙일 수 있었던 기능 상태를 가져옵니다.

기능명은 완전 수식 URI 입니다. 구현이 독자적인 기능을 정의할 수도 있습니다. 생성하는 DocumentBuilderFactory 또는 DocumentBuilder 가 그 기능을 지원할 수 없는 경우는,ParserConfigurationException 가 throw 됩니다. DocumentBuilderFactory 는 기능의 값을 표시할 수 있습니다만, 그 상태를 변경할 수 없습니다.

파라미터:

name - 기능명

반환값:

이름을 붙일 수 있었던 기능 상태

예외:

ParserConfigurationException - 작성하는 DocumentBuilderFactory 또는 DocumentBuilder 가 이 기능을 지원할 수 없는 경우

getSchema

public Schema  getSchema()

setSchema(Schema schema) 메소드를 개입시켜 지정된 Schema 객체를 가져옵니다.

반환값:

setSchema(Schema) 메소드를 개입시켜 마지막에 설정된 Schema 객체, 또는 DocumentBuilderFactory 가 작성되고 나서 메소드가 불려 가지 않은 경우는 null

예외:

UnsupportedOperationException - 구현이 이 메소드를 오버라이드(override) 하지 않는 경우

도입된 버젼:

1.5

setSchema

public void setSchema(Schema  schema)

이 팩토리로부터 작성된 퍼서에 의해 사용되는 Schema 를 설정합니다.

Schema 가 null 이외의 경우, 퍼서는 지금부터 작성된 발리 데이터를 사용해, 어플리케이션에 정보를 건네주기 전에 문서를 검증합니다. 　

발리 데이터에 의해 에러가 검출되면(자), 퍼서 자신이 에러를 검출했을 경우와 같게, 퍼서가 그 에러를 사용자 지정 ErrorHandler 에 보고합니다. 에러 핸들러가 설정되어 있지 않은 경우는, 그 에러는 무시되는지, throw 됩니다. 즉, 사용자 지정 ErrorHandler 가 설정되어 있는 경우는, 이러한 에러를 받아, 그렇지 않은 경우는 구현 고유의 디폴트의 에러 처리 규칙에 따라 처리될 필요가 있습니다.

발리 데이터는 해석의 결과를 변경하는 일이 있어 (예를 들어, 문서로부터 없어지고 있던 디폴트 값를 추가하는 등), 퍼서측에서 변경 끝난 DOM 트리를 어플리케이션이 받는 것을 확인할 필요가 있습니다.

최초로,Schema 로서 null 가 설정됩니다.

이 처리는 isValidating() 메소드가 false 를 돌려주었을 경우에서도 유효합니다. 　

http://java.sun.com/xml/jaxp/properties/schemaSource 프로퍼티 또는 http://java.sun.com/xml/jaxp/properties/schemaLanguage 프로퍼티을 Schema 객체와 함께 사용하면(자) 에러가 됩니다. newDocumentBuilder() 의 호출시에, 그 설정에 의해 ParserConfigurationException 예외가 발생합니다.

구현시의 주의

퍼서는, 모든 Schema 구현으로 동작할 필요가 있습니다. 다만, 퍼서 및 schema가 스펙에 기재되어 있는 결과를 내는 한, 구현 고유의 커스텀 기구를 사용할 수 있습니다.

파라미터:

schema - 사용하는 Schema, 또는 schema를 삭제하려면 null

예외:

UnsupportedOperationException - 구현이 이 메소드를 오버라이드(override) 하지 않는 경우

도입된 버젼:

1.5

setXIncludeAware

public void setXIncludeAware(boolean state)

XInclude 처리 상태를 설정합니다.

　

문서 인스턴스에 XInclude 마크 업이 발견되었을 경우,「XML Inclusions (XInclude) Version 1.0」으로 지정되고 있는 대로 처리할 필요가 있습니다.

　

XInclude 처리의 디폴트는 false 로 설정됩니다.

파라미터:

state - XInclude 처리를 true 또는 false 로 설정한다

예외:

UnsupportedOperationException - 구현이 이 메소드를 오버라이드(override) 하지 않는 경우

도입된 버젼:

1.5

isXIncludeAware

public boolean isXIncludeAware()

XInclude 처리 상태를 가져옵니다.

반환값:

XInclude 처리의 현재 상태

예외:

UnsupportedOperationException - 구현이 이 메소드를 오버라이드(override) 하지 않는 경우

도입된 버젼:

1.5