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
18//  $Id: Result.java 446598 2006-09-15 12:55:40Z jeremias $
19
20package javax.xml.transform;
21
22/**
23 * <p>An object that implements this interface contains the information
24 * needed to build a transformation result tree.</p>
25 *
26 * @author <a href="Jeff.Suttor@Sun.com">Jeff Suttor</a>
27 */
28public interface Result {
29
30    /**
31     * The name of the processing instruction that is sent if the
32     * result tree disables output escaping.
33     *
34     * <p>Normally, result tree serialization escapes & and < (and
35     * possibly other characters) when outputting text nodes.
36     * This ensures that the output is well-formed XML. However,
37     * it is sometimes convenient to be able to produce output that is
38     * almost, but not quite well-formed XML; for example,
39     * the output may include ill-formed sections that will
40     * be transformed into well-formed XML by a subsequent non-XML aware
41     * process. If a processing instruction is sent with this name,
42     * serialization should be output without any escaping. </p>
43     *
44     * <p>Result DOM trees may also have PI_DISABLE_OUTPUT_ESCAPING and
45     * PI_ENABLE_OUTPUT_ESCAPING inserted into the tree.</p>
46     *
47     * @see <a href="http://www.w3.org/TR/xslt#disable-output-escaping">disable-output-escaping in XSLT Specification</a>
48     */
49    public static final String PI_DISABLE_OUTPUT_ESCAPING =
50        "javax.xml.transform.disable-output-escaping";
51
52    /**
53     * The name of the processing instruction that is sent
54     * if the result tree enables output escaping at some point after having
55     * received a PI_DISABLE_OUTPUT_ESCAPING processing instruction.
56     *
57     * @see <a href="http://www.w3.org/TR/xslt#disable-output-escaping">disable-output-escaping in XSLT Specification</a>
58     */
59    public static final String PI_ENABLE_OUTPUT_ESCAPING =
60        "javax.xml.transform.enable-output-escaping";
61
62    /**
63     * Set the system identifier for this Result.
64     *
65     * <p>If the Result is not to be written to a file, the system identifier is optional.
66     * The application may still want to provide one, however, for use in error messages
67     * and warnings, or to resolve relative output identifiers.</p>
68     *
69     * @param systemId The system identifier as a URI string.
70     */
71    public void setSystemId(String systemId);
72
73    /**
74     * Get the system identifier that was set with setSystemId.
75     *
76     * @return The system identifier that was set with setSystemId,
77     * or null if setSystemId was not called.
78     */
79    public String getSystemId();
80}
81