1/*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements.  See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License.  You may obtain a copy of the License at
8 *
9 *     http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17
18package java.sql;
19
20import java.io.InputStream;
21import java.io.OutputStream;
22import java.io.Reader;
23import java.io.Writer;
24import javax.xml.transform.Result;
25import javax.xml.transform.Source;
26
27/**
28 * Maps SQL's XML type into Java.
29 */
30public interface SQLXML {
31    /**
32     * Frees any resources held by this object. After {@code free} is called, calling
33     * method other than {@code free} will throw {@code SQLException} (calling {@code free}
34     * repeatedly will do nothing).
35     * @throws SQLException
36     */
37    void free() throws SQLException;
38
39    /**
40     * Returns a stream that can be used to read binary data from this SQL {@code XML} object.
41     * @throws SQLException if an error occurs accessing the data
42     */
43    InputStream getBinaryStream() throws SQLException;
44
45    /**
46     * Returns a stream that can be used to write binary data to this SQL {@code XML} object.
47     * @throws SQLException if an error occurs accessing the data
48     */
49    OutputStream setBinaryStream() throws SQLException;
50
51    /**
52     * Returns a reader that can be used to read character data from this SQL {@code XML} object.
53     * @throws SQLException if an error occurs accessing the data
54     */
55    Reader getCharacterStream() throws SQLException;
56
57    /**
58     * Returns a writer that can be used to write character data to this SQL {@code XML} object.
59     * @throws SQLException if an error occurs accessing the data
60     */
61    Writer setCharacterStream() throws SQLException;
62
63    /**
64     * Returns this object's data as an XML string.
65     * @throws SQLException if an error occurs accessing the data
66     */
67    String getString() throws SQLException;
68
69    /**
70     * Sets this object's data to the given XML string.
71     * @throws SQLException if an error occurs accessing the data
72     */
73    void setString(String value) throws SQLException;
74
75    /**
76     * Returns a {@link Source} for reading this object's data.
77     * @throws SQLException if an error occurs accessing the data
78     */
79    <T extends Source> T getSource(Class<T> sourceClass) throws SQLException;
80
81    /**
82     * Returns a {@link Result} for writing this object's data.
83     * @throws SQLException if an error occurs accessing the data
84     */
85    <T extends Result> T setResult(Class<T> resultClass) throws SQLException;
86}
87