java.sql
인터페이스 SQLXML

public interface SQLXML

SQL XML 형의 JavaTM 프로그램 언어에서의 매핑입니다. XML 는, XML 치를 데이타베이스 테이블의 은행내에 열의 값으로 해서 포함하는 편입의 형태입니다. 디폴트에서는, 드라이버는 SQLXML 객체를 데이터 그 자체는 아니고, XML 데이터에의 논리 포인터로서 포함합니다. SQLXML 객체는, 그것이 생성된 트랜잭션(transaction)의 기간중에 유효합니다.

SQLXML 인터페이스는, String, Reader 또는 Writer, 혹은 Stream 로서 XML 치에 액세스하기 위한 메소드를 제공합니다. XML 치는, Source 로부터 액세스 하거나 Result 로서 설정하거나 할 수가 있어 XML Parser API (DOM, SAX, StAX 등), XSLT 변환, 및 XPath 평가로 사용할 수 있습니다.

ResultSet, CallableStatement, PreparedStatement 의 각 인터페이스의 메소드 (getSQLXML 등)를 사용하면(자), 프로그래머는 XML 치에 액세스 할 수 있습니다. 한층 더 이 인터페이스는 XML 치를 갱신하기 위한 메소드를 갖추고 있습니다.

SQLXML 인스턴스의 XML 치는, 다음의 식을 사용해 BinaryStream 로서 취득할 수 있습니다.

   SQLXML sqlxml = resultSet.getSQLXML(column);
   InputStream binaryStream = sqlxml.getBinaryStream();
 

예를 들어, DOM 퍼서로 XML 치를 구문 분석 하려면 , 다음과 같이 합니다.

   DocumentBuilder parser = DocumentBuilderFactory.newInstance(). newDocumentBuilder();
   Document result = parser.parse(binaryStream);
 

핸들러에 대한 SAX 퍼서로 XML 치를 구문 분석 하려면 , 다음과 같이 합니다.

   SAXParser parser = SAXParserFactory.newInstance(). newSAXParser();
   parser.parse(binaryStream, myHandler);
 

StAX 퍼서로 XML 치를 구문 분석 하려면 , 다음과 같이 합니다.

   XMLInputFactory factory = XMLInputFactory.newInstance();
   XMLStreamReader streamReader = factory.createXMLStreamReader(binaryStream);
 

데이타베이스는 XML 의 최적화 표현을 사용할 수 있기 (위해)때문에, getSource() 및 setResult()를 사용해 값에 액세스 하면(자), 스트림 표현에의 직렬화나 XML 의 구문 분석을 사용하지 않고 , 처리의 퍼포먼스를 향상시킬 수가 있습니다.

예를 들어 DOM Document 노드를 가져오려면 , 다음과 같이 합니다.

   DOMSource domSource = sqlxml.getSource(DOMSource.class);
   Document document = (Document) domSource.getNode();
 

DOM Document 노드의 값을 myNode 로 설정하려면 , 다음과 같이 합니다.

   DOMResult domResult = sqlxml.setResult(DOMResult.class);
   domResult.setNode(myNode);
 

SAX 이벤트를 핸들러에 송신하려면 , 다음과 같이 합니다.

   SAXSource saxSource = sqlxml.getSource(SAXSource.class);
   XMLReader xmlReader = saxSource.getXMLReader();
   xmlReader.setContentHandler(myHandler);
   xmlReader.parse(saxSource.getInputSource());
 

SAX 이벤트로부터의 결과의 값을 설정하려면 , 다음과 같이 합니다.

   SAXResult saxResult = sqlxml.setResult(SAXResult.class);
   ContentHandler contentHandler = saxResult.getXMLReader(). getContentHandler();
   contentHandler.startDocument();
   // set the XML elements and attributes into the result
   contentHandler.endDocument();
 

StAX 이벤트를 가져오려면 , 다음과 같이 합니다.

   StAXSource staxSource = sqlxml.getSource(StAXSource.class);
   XMLStreamReader streamReader = staxSource.getXMLStreamReader();
 

StAX 이벤트로부터의 결과의 값을 설정하려면 , 다음과 같이 합니다.

   StAXResult staxResult = sqlxml.setResult(StAXResult.class);
   XMLStreamWriter streamWriter = staxResult.getXMLStreamWriter();
 

파일 resultFile 에의 xsltFile 출력으로 XSLT 를 사용해, XML 치의 XSLT 변환을 실행하려면 , 다음과 같이 합니다.

   File xsltFile = new File("a.xslt");
   File myFile = new File("result.xml");
   Transformer xslt = TransformerFactory.newInstance(). newTransformer(new StreamSource(xsltFile));
   Source source = sqlxml.getSource(null);
   Result result = new StreamResult(myFile);
   xslt.transform(source, result);
 

XML 치의 XPath 식을 평가하려면 , 다음과 같이 합니다.

   XPath xpath = XPathFactory.newInstance(). newXPath();
   DOMSource domSource = sqlxml.getSource(DOMSource.class);
   Document document = (Document) domSource.getNode();
   String expression = "/foo/@bar";
   String barValue = xpath.evaluate(expression, document);
 

XML 치를 XSLT 변환의 결과로 설정하려면 , 다음과 같이 합니다.

   File sourceFile = new File("source.xml");
   Transformer xslt = TransformerFactory.newInstance(). newTransformer(new StreamSource(xsltFile));
   Source streamSource = new StreamSource(sourceFile);
   Result result = sqlxml.setResult(null);
   xslt.transform(streamSource, result);
 

newTransformer()를 호출하는 것으로 지정되는 항등변환을 사용해, 임의의 Source 를 Result 로 변환할 수 있습니다.

   Transformer identity = TransformerFactory.newInstance(). newTransformer();
   Source source = sqlxml.getSource(null);
   File myFile = new File("result.xml");
   Result result = new StreamResult(myFile);
   identity.transform(source, result);
 

Source 의 내용을 표준 출력에 기입하려면 , 다음과 같이 합니다.

   Transformer identity = TransformerFactory.newInstance(). newTransformer();
   Source source = sqlxml.getSource(null);
   Result result = new StreamResult(System.out);
   identity.transform(source, result);
 

DOMResult 로부터 DOMSource 를 작성하려면 , 다음과 같이 합니다.

    DOMSource domSource = new DOMSource(domResult.getNode()); 
 

불완전한 XML 치나 무효인 XML 치가 원인으로, 설정시에 SQLException 가 발생하거나 execute()의 발생시에 이 예외가 발생하거나 하는 일이 있습니다. 모든 스트림은, execute()의 발생전에 클로즈 할 필요가 있습니다. 그렇지 않으면 SQLException 가 throw 됩니다.

SQLXML 객체에 대한 XML 치의 읽고 쓰기는, 많아도 1 회 발생할 가능성이 있습니다. read 가능 및 읽어들여 불가능의 개념적 상태에 의해, 몇개의 읽어들여 API 로 값을 돌려줄까 예외를 throw 할지가 판단됩니다. 기입 가능 및 기입해 불가능의 개념적 상태에 의해, 몇개의 기입해 API 로 값을 설정할까 예외를 throw 할지가 판단됩니다.

free() 또는 읽어들여 API (getBinaryStream(), getCharacterStream(), getSource(), getString())가 불려 가면(자), 상태는 읽어들여 가능으로부터 읽어들여 불가능하게 옮깁니다. 구현에 따라서는, 이 때에 상태를 기입해 불가능하게 변경할 수도 있습니다.

free() 또는 기입해 API (setBinaryStream(), setCharacterStream(), setResult(), setString())가 불려 가면(자), 상태는 기입해 가능으로부터 기입해 불가능하게 옮깁니다. 구현에 따라서는, 이 때에 상태를 읽어들여 불가능하게 변경할 수도 있습니다.

JDBC 드라이버가 그 데이터형을 지원하는 경우는,SQLXML 인터페이스의 모든 메소드가 완전하게 구현될 필요가 있습니다.

도입된 버젼:

1.6

관련 항목:

javax.xml.parsers , javax.xml.stream , javax.xml.transform , javax.xml.xpath

메소드의 개요

void	free () 이 메소드는 이 객체를 클로즈 해, 이 객체가 보관 유지하고 있던 자원을 해제합니다.
InputStream	getBinaryStream () 이 SQLXML 인스턴스에 의해 지정된 XML 치를 스트림로서 꺼냅니다.
Reader	getCharacterStream () 이 SQLXML 인스턴스에 의해 지정된 XML 치를 java.io.Reader 객체로서 가져옵니다.
<T extends Source > T	getSource (Class <T> sourceClass) 이 SQLXML 인스턴스에 의해 지정된 XML 치를 읽어들이기 위한 Source 를 돌려줍니다.
String	getString () 이 SQLXML 인스턴스에 의해 지정된 XML 치의 캐릭터 라인 표현을 돌려줍니다.
OutputStream	setBinaryStream () 이 SQLXML 인스턴스가 나타내는 XML 치에의 기입해에 사용하는 스트림을 가져옵니다.
Writer	setCharacterStream () 이 SQLXML 인스턴스가 나타내는 XML 치에의 기입해에 사용하는 스트림을 가져옵니다.
<T extends Result > T	setResult (Class <T> resultClass) 이 SQLXML 인스턴스에 의해 지정된 XML 치를 설정하기 위한 Result 를 돌려줍니다.
void	setString (String value) 이 SQLXML 인스턴스에 의해 지정된 XML 치가 지정된 String 표현으로 설정합니다.

메소드의 상세

free

void free()
          throws SQLException 

이 메소드는 이 객체를 클로즈 해, 이 객체가 보관 유지하고 있던 자원을 해제합니다. 이 메소드가 불려 가면(자), SQL XML 객체는 무효가 되어, 읽어들여 가능하게도 기입해 가능하게도 되지 않습니다. free 가 불려 가면(자),free 이외의 메소드를 호출하려고 해도,SQLException 가 throw 됩니다. free 를 여러 차례 호출했을 경우, 2 번째 이후의 free 호출은 아무것도 실시하지 않는 것으로서 다루어집니다.

예외:

SQLException - XML 치를 해제할 경우에 에러가 발생했을 경우

SQLFeatureNotSupportedException - JDBC 드라이버가 이 메소드를 지원하지 않는 경우

도입된 버젼:

1.6

getBinaryStream

InputStream  getBinaryStream()
                            throws SQLException 

이 SQLXML 인스턴스에 의해 지정된 XML 치를 스트림로서 꺼냅니다. 입력 스트림의 바이트는, XML 1.0 스펙의 부록 F 에 따라 해석됩니다. ResultSet 의 지정된 열이 java.sql.Types 형의 SQLXML 인 경우, 이 메소드의 동작은 ResultSet.getBinaryStream()와 같게 됩니다.

이 메소드가 불려 가면(자), SQL XML 객체는 읽어들여 불가능하게 되어, 구현에 따라서는 기입해 불가능하게 될 수도 있습니다.

반환값:

XML 데이터를 포함하는 스트림

예외:

SQLException - XML 치를 처리할 경우에 에러가 발생했을 경우. 상태가 읽어들여 불가능한 경우는, 예외가 throw 된다

SQLFeatureNotSupportedException - JDBC 드라이버가 이 메소드를 지원하지 않는 경우

도입된 버젼:

1.6

setBinaryStream

OutputStream  setBinaryStream()
                             throws SQLException 

이 SQLXML 인스턴스가 나타내는 XML 치에의 기입해에 사용하는 스트림을 가져옵니다. 스트림은 위치 0 으로부터 개시합니다. 스트림의 바이트는, XML 1.0 스펙의 부록 F 에 따라 해석됩니다. ResultSet 의 지정된 열이 java.sql.Types 형의 SQLXML 인 경우, 이 메소드의 동작은 ResultSet.updateBinaryStream()와 같게 됩니다.

이 메소드가 불려 가면(자), SQL XML 객체는 기입해 불가능하게 되어, 구현에 따라서는 읽어들여 불가능하게 될 수도 있습니다.

반환값:

데이터가 기입해지는 스트림

예외:

SQLException - XML 치를 처리할 경우에 에러가 발생했을 경우. 상태가 기입해 불가능한 경우는, 예외가 throw 된다

SQLFeatureNotSupportedException - JDBC 드라이버가 이 메소드를 지원하지 않는 경우

도입된 버젼:

1.6

getCharacterStream

Reader  getCharacterStream()
                          throws SQLException 

이 SQLXML 인스턴스에 의해 지정된 XML 치를 java.io.Reader 객체로서 가져옵니다. 이 스트림의 형식은, org.xml.sax.InputSource 로 정의됩니다. 스트림의 문자는, XML 1.0 스펙의 섹션 2 로 부록 B 에 따라, XML 의 Unicode 코드 포인트를 나타냅니다. Unicode 이외의 인코딩 선언이 존재할 가능성은 있습니다만, 스트림의 인코딩은 Unicode 입니다. ResultSet 의 지정된 열이 java.sql.Types 형의 SQLXML 인 경우, 이 메소드의 동작은 ResultSet.getCharacterStream()와 같게 됩니다.

이 메소드가 불려 가면(자), SQL XML 객체는 읽어들여 불가능하게 되어, 구현에 따라서는 기입해 불가능하게 될 수도 있습니다.

반환값:

XML 데이터를 포함하는 스트림

예외:

SQLException - XML 치를 처리할 경우에 에러가 발생했을 경우. 이 예외의 getCause() 메소드에 의해, 보다 상세한 예외가 제공되는 일이 있다 (예를 들어 스트림에 유효한 문자가 포함되지 않은 경우). 상태가 읽어들여 불가능한 경우는, 예외가 throw 된다

SQLFeatureNotSupportedException - JDBC 드라이버가 이 메소드를 지원하지 않는 경우

도입된 버젼:

1.6

setCharacterStream

Writer  setCharacterStream()
                          throws SQLException 

이 SQLXML 인스턴스가 나타내는 XML 치에의 기입해에 사용하는 스트림을 가져옵니다. 이 스트림의 형식은, org.xml.sax.InputSource 로 정의됩니다. 스트림의 문자는, XML 1.0 스펙의 섹션 2 로 부록 B 에 따라, XML 의 Unicode 코드 포인트를 나타냅니다. Unicode 이외의 인코딩 선언이 존재할 가능성은 있습니다만, 스트림의 인코딩은 Unicode 입니다. ResultSet 의 지정된 열이 java.sql.Types 형의 SQLXML 인 경우, 이 메소드의 동작은 ResultSet.updateCharacterStream()와 같게 됩니다.

이 메소드가 불려 가면(자), SQL XML 객체는 기입해 불가능하게 되어, 구현에 따라서는 읽어들여 불가능하게 될 수도 있습니다.

반환값:

데이터가 기입해지는 스트림

예외:

SQLException - XML 치를 처리할 경우에 에러가 발생했을 경우. 이 예외의 getCause() 메소드에 의해, 보다 상세한 예외가 제공되는 일이 있다 (예를 들어 스트림에 유효한 문자가 포함되지 않은 경우). 상태가 기입해 불가능한 경우는, 예외가 throw 된다

SQLFeatureNotSupportedException - JDBC 드라이버가 이 메소드를 지원하지 않는 경우

도입된 버젼:

1.6

getString

String  getString()
                 throws SQLException 

이 SQLXML 인스턴스에 의해 지정된 XML 치의 캐릭터 라인 표현을 돌려줍니다. 이 String 의 형식은, org.xml.sax.InputSource 로 정의됩니다. 스트림의 문자는, XML 1.0 스펙의 섹션 2 로 부록 B 에 따라, XML 의 Unicode 코드 포인트를 나타냅니다. Unicode 이외의 인코딩 선언이 존재할 가능성은 있습니다만, String 의 인코딩은 Unicode 입니다. ResultSet 의 지정된 열이 java.sql.Types 형의 SQLXML 인 경우, 이 메소드의 동작은 ResultSet.getString()와 같게 됩니다.

이 메소드가 불려 가면(자), SQL XML 객체는 읽어들여 불가능하게 되어, 구현에 따라서는 기입해 불가능하게 될 수도 있습니다.

반환값:

이 SQLXML 인스턴스에 의해 지정된 XML 치의 캐릭터 라인 표현

예외:

SQLException - XML 치를 처리할 경우에 에러가 발생했을 경우. 이 예외의 getCause() 메소드에 의해, 보다 상세한 예외가 제공되는 일이 있다 (예를 들어 스트림에 유효한 문자가 포함되지 않은 경우). 상태가 읽어들여 불가능한 경우는, 예외가 throw 된다

SQLFeatureNotSupportedException - JDBC 드라이버가 이 메소드를 지원하지 않는 경우

도입된 버젼:

1.6

setString

void setString(String  value)
               throws SQLException 

이 SQLXML 인스턴스에 의해 지정된 XML 치가 지정된 String 표현으로 설정합니다. 이 String 의 형식은, org.xml.sax.InputSource 로 정의됩니다. 스트림의 문자는, XML 1.0 스펙의 섹션 2 로 부록 B 에 따라, XML 의 Unicode 코드 포인트를 나타냅니다. Unicode 이외의 인코딩 선언이 존재할 가능성은 있습니다만, String 의 인코딩은 Unicode 입니다. ResultSet 의 지정된 열이 java.sql.Types 형의 SQLXML 인 경우, 이 메소드의 동작은 ResultSet.updateString()와 같게 됩니다.

이 메소드가 불려 가면(자), SQL XML 객체는 기입해 불가능하게 되어, 구현에 따라서는 읽어들여 불가능하게 될 수도 있습니다.

파라미터:

value - XML 치

예외:

SQLException - XML 치를 처리할 경우에 에러가 발생했을 경우. 이 예외의 getCause() 메소드에 의해, 보다 상세한 예외가 제공되는 일이 있다 (예를 들어 스트림에 유효한 문자가 포함되지 않은 경우). 상태가 기입해 불가능한 경우는, 예외가 throw 된다

SQLFeatureNotSupportedException - JDBC 드라이버가 이 메소드를 지원하지 않는 경우

도입된 버젼:

1.6

getSource

<T extends Source > T getSource(Class <T> sourceClass)
                           throws SQLException 

이 SQLXML 인스턴스에 의해 지정된 XML 치를 읽어들이기 위한 Source 를 돌려줍니다. Source 는, XML 퍼서 및 XSLT 트랜스 포머에의 입력으로서 사용됩니다.

XML 퍼서의 Source 에서는, 디폴트로 이름 공간 처리가 있습니다. Source 의 systemID 는 구현으로 결정됩니다.

이 메소드가 불려 가면(자), SQL XML 객체는 읽어들여 불가능하게 되어, 구현에 따라서는 기입해 불가능하게 될 수도 있습니다.

SAX 는 콜백 아키텍쳐(architecture)이기 (위해)때문에, 반환되는 SAXSource 는, 해석으로부터의 SAX 이벤트를 수신하는 컨텐츠 핸들러로 설정되지 않으면 안됩니다. 컨텐츠 핸들러는, XML 의 내용에 근거해 콜백을 수신합니다.

   SAXSource saxSource = sqlxml.getSource(SAXSource.class);
   XMLReader xmlReader = saxSource.getXMLReader();
   xmlReader.setContentHandler(myHandler);
   xmlReader.parse(saxSource.getInputSource());
 

파라미터:

sourceClass - 소스의 클래스, 또는 null. 클래스가 null 의 경우, 벤더 고유의 Source 구현이 반환된다. 적어도 다음의 클래스가 지원된다

   javax.xml.transform.dom.DOMSource - DOMSource 를 돌려준다
   javax.xml.transform.sax.SAXSource - SAXSource 를 돌려준다
   javax.xml.transform.stax.StAXSource - StAXSource 를 돌려준다
   javax.xml.transform.stream.StreamSource - StreamSource 를 돌려준다
 

반환값:

XML 치의 읽어들여에 사용하는 소스

예외:

SQLException - XML 치를 처리할 경우에 에러가 발생했을 경우, 또는 이 기능이 지원되어 있지 않은 경우. 이 예외의 getCause() 메소드에 의해, 보다 상세한 예외가 제공되는 일이 있다 (예를 들어 XML 퍼서 예외가 발생했을 경우). 상태가 읽어들여 불가능한 경우는, 예외가 throw 된다

SQLFeatureNotSupportedException - JDBC 드라이버가 이 메소드를 지원하지 않는 경우

도입된 버젼:

1.6

setResult

<T extends Result > T setResult(Class <T> resultClass)
                           throws SQLException 

이 SQLXML 인스턴스에 의해 지정된 XML 치를 설정하기 위한 Result 를 돌려줍니다.

Result 의 systemID 는 구현으로 결정됩니다.

이 메소드가 불려 가면(자), SQL XML 객체는 기입해 불가능하게 되어, 구현에 따라서는 읽어들여 불가능하게 될 수도 있습니다.

SAX 는 콜백 아키텍쳐(architecture)이기 (위해)때문에, 반환되는 SAXResult 에는, XML 의 내용에 근거해 SAX 이벤트를 수신하는 컨텐츠 핸들러를 할당할 수 있습니다. 값을 할당하려면 , XML 문서의 내용을 사용해 컨텐츠 핸들러를 호출해 주세요.

   SAXResult saxResult = sqlxml.setResult(SAXResult.class);
   ContentHandler contentHandler = saxResult.getXMLReader(). getContentHandler();
   contentHandler.startDocument();
   // set the XML elements and attributes into the result
   contentHandler.endDocument();
 

파라미터:

resultClass - 결과의 클래스, 또는 null. resultClass 가 null 의 경우, 벤더 고유의 Result 구현이 반환된다. 적어도 다음의 클래스가 지원된다

   javax.xml.transform.dom.DOMResult - DOMResult 를 돌려준다
   javax.xml.transform.sax.SAXResult - SAXResult 를 돌려준다
   javax.xml.transform.stax.StAXResult - StAXResult 를 돌려준다
   javax.xml.transform.stream.StreamResult - StreamResult 를 돌려준다
 

반환값:

XML 치의 설정에 사용하는 Result 를 돌려준다

예외:

SQLException - XML 치를 처리할 경우에 에러가 발생했을 경우, 또는 이 기능이 지원되어 있지 않은 경우. 이 예외의 getCause() 메소드에 의해, 보다 상세한 예외가 제공되는 일이 있다 (예를 들어 XML 퍼서 예외가 발생했을 경우). 상태가 기입해 불가능한 경우는, 예외가 throw 된다

SQLFeatureNotSupportedException - JDBC 드라이버가 이 메소드를 지원하지 않는 경우

도입된 버젼:

1.6