1 /* Copyright 2004 The Apache Software Foundation
2 *
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16 package org.apache.xmlbeans;
17
18 /**
19 * This class is used to attach arbitrary information to an XML
20 * document. It also defines several well-known types of
21 * information that can be attached or found on a document.
22 * <p>
23 * For example, suppose you wanted to associate a filename
24 * with the document containing an xml object "xobj". This
25 * could be done via the following code:
26 * <p>
27 * tokenSource.documentProperties().set(XmlDocumentProperties.NAME, "MyFilename.xml");
28 * <p>
29 * To fetch the filename later, given an xobj2 anywhere in the
30 * same document, you can write:
31 * <p>
32 * filename = (String)tokenSource.documentProperties().get(XmlDocumentProperties.NAME);
33 */
34 public abstract class XmlDocumentProperties
35 {
36 /**
37 * Sets the name of the XML document file. Typically a URL, but may
38 * be any String.
39 * @param sourceName the name to set
40 * @see XmlOptions#setDocumentSourceName
41 */
42 public void setSourceName ( String sourceName ) { put( SOURCE_NAME, sourceName ); }
43 /**
44 * Returns the name of the XML document file. Typically a URL, but may
45 * be any String.
46 * @see XmlOptions#setDocumentSourceName
47 */
48 public String getSourceName ( ) { return (String) get( SOURCE_NAME ); }
49
50 /**
51 * Sets the encoding to use for the XML document. Should be a valid
52 * XML encoding string.
53 * @param encoding the ISO encoding name
54 * @see XmlOptions#setCharacterEncoding
55 */
56 public void setEncoding ( String encoding ) { put( ENCODING, encoding ); }
57 /**
58 * Returns the encoding used for the XML document, as an ISO encoding name.
59 * @see XmlOptions#setCharacterEncoding
60 */
61 public String getEncoding ( ) { return (String) get( ENCODING ); }
62
63 /**
64 * Sets the XML version string to use in the <?xml?> declaration.
65 * (The XML specification is quite stable at "1.0".)
66 * @param version the XML version string
67 */
68 public void setVersion ( String version ) { put( VERSION, version ); }
69 /**
70 * Returns the XML version string used in the <?xml?> declaration.
71 */
72 public String getVersion ( ) { return (String) get( VERSION ); }
73
74 /**
75 * Sets the standalone property.
76 * @param standalone whether standalone is true or not
77 */
78 public void setStandalone ( boolean standalone ) { put( STANDALONE, standalone ? "true" : null ); }
79 /**
80 * Returns the standalone property
81 */
82 public boolean getStandalone ( ) { return get( STANDALONE ) != null; }
83
84 /**
85 * Sets the DOCTYPE name use in the <!DOCTYPE> declaration.
86 * @param doctypename the doctypename
87 */
88 public void setDoctypeName ( String doctypename ) { put( DOCTYPE_NAME, doctypename ); }
89 /**
90 * Returns the DOCTYPE name used in the <!DOCTYPE> declaration.
91 */
92 public String getDoctypeName ( ) { return (String) get( DOCTYPE_NAME ); }
93
94 /**
95 * Sets the DOCTYPE public ID to use in the <!DOCTYPE> declaration.
96 * @param publicid the public ID
97 */
98 public void setDoctypePublicId ( String publicid ) { put( DOCTYPE_PUBLIC_ID, publicid ); }
99 /**
100 * Returns the DOCTYPE public ID used in the <!DOCTYPE> declaration.
101 */
102 public String getDoctypePublicId ( ) { return (String) get( DOCTYPE_PUBLIC_ID ); }
103
104 /**
105 * Sets the DOCTYPE system ID to use in the <!DOCTYPE> declaration.
106 * @param systemid the system ID
107 */
108 public void setDoctypeSystemId ( String systemid ) { put( DOCTYPE_SYSTEM_ID, systemid ); }
109 /**
110 * Returns the DOCTYPE system ID used in the <!DOCTYPE> declaration.
111 */
112 public String getDoctypeSystemId ( ) { return (String) get( DOCTYPE_SYSTEM_ID ); }
113
114 /**
115 * Sets the message digest used to summarize the document.
116 * @param digest the bytes of the digest
117 *
118 * @see XmlOptions#setLoadMessageDigest
119 */
120 public void setMessageDigest( byte[] digest ) { put( MESSAGE_DIGEST, digest ); }
121 /**
122 * Returns the message digest used to summarize the document.
123 *
124 * @see XmlOptions#setLoadMessageDigest
125 */
126 public byte[] getMessageDigest( ) { return (byte[]) get( MESSAGE_DIGEST ); }
127
128 /**
129 * Used to store the original name (a String) for
130 * the source from which the XML document was loaded.
131 * This name, if present, is used to identify the
132 * document when reporting validation or comilation errors.
133 *
134 * XmlObject.Factory.parse(File) and SchemaTypeLoader.loadInstance(File)
135 * both automatically set this value to the filename.
136 */
137 public static final Object SOURCE_NAME = new Object();
138
139 /**
140 * Document encoding
141 */
142 public static final Object ENCODING = new Object();
143
144 /**
145 * Document version
146 */
147 public static final Object VERSION = new Object();
148
149 /**
150 * Document standlone
151 */
152 public static final Object STANDALONE = new Object();
153
154 /**
155 * Doc type name
156 */
157 public static final Object DOCTYPE_NAME = new Object();
158
159 /**
160 * Doc type public id
161 */
162 public static final Object DOCTYPE_PUBLIC_ID = new Object();
163
164 /**
165 * Doc type system id
166 */
167 public static final Object DOCTYPE_SYSTEM_ID = new Object();
168
169 /**
170 * SHA message digest
171 */
172 public static final Object MESSAGE_DIGEST = new Object();
173
174 /**
175 * Attaches a value to the root of the document containing
176 * the given token source.
177 *
178 * @param key The key: there can be one value for each key.
179 * @param value The value to attach to the document.
180 */
181 public abstract Object put ( Object key, Object value );
182
183 /**
184 * Returns a value previously attached to a document using set.
185 *
186 * @param key The key: this is the key that was previously
187 * passed to set to store the value.
188 * @return The saved value, or null if none is found.
189 */
190 public abstract Object get ( Object key );
191
192 /**
193 * Removes a value previously attached to a document using set.
194 *
195 * @param key The key: this is the key that was previously
196 * passed to set to store the value.
197 */
198 public abstract Object remove ( Object key );
199 }
200