XMLResource


1   /**
2    * <copyright>
3    *
4    * Copyright (c) 2002-2005 IBM Corporation and others.
5    * All rights reserved.   This program and the accompanying materials
6    * are made available under the terms of the Eclipse Public License v1.0
7    * which accompanies this distribution, and is available at
8    * http://www.eclipse.org/legal/epl-v10.html
9    *
10   * Contributors:
11   *   IBM - Initial API and implementation
12   *
13   * </copyright>
14   *
15   * $Id: XMLResource.java,v 1.27 2005/06/15 21:16:49 elena Exp $
16   */
17  package org.eclipse.emf.ecore.xmi;
18  
19  import java.io.IOException  ;
20  import java.io.InputStream  ;
21  import java.io.OutputStream  ;
22  import java.util.List  ;
23  import java.util.Map  ;
24  
25  import org.eclipse.emf.ecore.EClass;
26  import org.eclipse.emf.ecore.EClassifier;
27  import org.eclipse.emf.ecore.ENamedElement;
28  import org.eclipse.emf.ecore.EObject;
29  import org.eclipse.emf.ecore.EPackage;
30  import org.eclipse.emf.ecore.EStructuralFeature;
31  import org.eclipse.emf.ecore.resource.Resource;
32  import org.eclipse.emf.ecore.util.ExtendedMetaData;
33  import org.w3c.dom.Document  ;
34  import org.w3c.dom.Node  ;
35  
36  /**
37   * This interface represents an XML resource. You can use it to load
38   * and save XML files. This initial implementation of XML serialization
39   * and deserialization is incomplete but will be completed shortly.
40   */
41  public interface XMLResource extends Resource
42  {
43    /**
44     * Specify a parser pool to be used for loading XML documents from InputStream.
45     * You need to provide a XMLParserPool as the value of this option.
46     * <p>
47     * This option can dramatically improve performance for deserialization (loading) of XML resource.
48     * </p>
49     * @see org.eclipse.emf.ecore.xmi.XMLParserPool
50     */
51    String   OPTION_USE_PARSER_POOL = "USE_PARSER_POOL";
52    
53    /**
54     * <p>
55     * Specify a map {@link Map} to be used during the subsequent loading of XML documents.
56     * This is mapping between XML name, namespace and an EClass to the corresponding EStructuralFeature.
57     * </p>
58     * <p>
59     * This option can significantly improve performance for deserialization (loading) of multiple XML resources
60     * which are based on the same model (XML Schema or Ecore). 
61     * </p>
62     * @see org.eclipse.emf.ecore.EClass
63     * @see org.eclipse.emf.ecore.EStructuralFeature
64     */
65    String   OPTION_USE_XML_NAME_TO_FEATURE_MAP = "USE_XML_NAME_TO_FEATURE_MAP";
66    
67    /**
68     * Specify a place holder {@link List} for caching information during the subsequent saving of XML documents.
69     * This option can improve performance for serialization (saving) of multiple XML resources. This option
70     * is similar to the OPTION_USE_XML_NAME_TO_FEATURE_MAP which is used for deserialization (loading).
71     */
72    String   OPTION_USE_CACHED_LOOKUP_TABLE = "USE_CACHED_LOOKUP_TABLE";
73    
74    /**
75     * Generic option for enable caching (during save and load) to improve performance.
76     * Note: this option might change in the future to define how the caching is done.
77     */
78    String   OPTION_CONFIGURATION_CACHE = "CONFIGURATION_CACHE";
79    
80    /**
81     * Use XMLTypeInfo to determine whether type information (xsi:type/xmi:type) is
82     * to be serialized for references.
83     */
84    String   OPTION_SAVE_TYPE_INFORMATION = "SAVE_TYPE_INFORMATION";
85    
86    /**
87     * Specify parser features with their corresponding values, 
88     * i.e., <code>true</code> or <code>false</code> using {@link Map}.  
89     * This option is applicable during loading of XML resources from an InputStream
90     */
91    String   OPTION_PARSER_FEATURES = "PARSER_FEATURES";
92    
93    /**
94     * Specify parser properties with their corresponding values using a {@link Map}.
95     * This option is applicable during loading of XML resources from an InputStream.
96     */
97    String   OPTION_PARSER_PROPERTIES = "PARSER_PROPERTIES";
98    
99    /**
100    * Determines whether comments and CDATA will be preserved in any mixed text processing.
101    * This option is applicable for loading XML resources (from DOM node or an InputStream)
102    */
103   String   OPTION_USE_LEXICAL_HANDLER = "USE_LEXICAL_HANDLER";
104   
105   /**
106    * This is option should be used when loading a resource from a DOM Element node, to specify
107    * that load method should take into account all the namespaces declarations in scope for this node 
108    * (by visiting parents of the node being loaded). 
109    * Otherwise, user have to make sure that Element node being loaded has namespace well-formed content.
110    * <p>
111    * Note that loading will only succeed if the subset of DOM being loaded could be treated as a valid resource according
112    * to the model. </p>
113    */
114   String   OPTION_DOM_USE_NAMESPACES_IN_SCOPE = "DOM_USE_NAMESPACES_IN_SCOPE";
115 
116   /**
117    * This option allows you to tailor the XML serialization of objects. 
118    * You should provide an ExtendedMetaData as the value of this option.
119    * @see org.eclipse.emf.ecore.util.BasicExtendedMetaData
120    */
121   String   OPTION_EXTENDED_META_DATA = "EXTENDED_META_DATA";
122   
123   /** 
124    * This option allows to specify an EClass for the implementation for anyType.
125    * @see #OPTION_ANY_SIMPLE_TYPE
126    * @see org.eclipse.emf.ecore.sdo.SDOPackage#getEDataObjectAnyType()
127    */
128   String   OPTION_ANY_TYPE = "ANY_TYPE";
129   
130   /** 
131    * This option allows to specify an EClass for the implementation for anySimpleType.
132    * @see #OPTION_ANY_TYPE
133    * @see org.eclipse.emf.ecore.sdo.SDOPackage#getEDataObjectSimpleAnyType()
134    */
135   String   OPTION_ANY_SIMPLE_TYPE ="ANY_SIMPLE_TYPE";
136 
137   /**
138    * This save option allows you to tailor the XML serialization of
139    * objects. You should provide an XMLMap as the value of this option.
140    * <p>
141    * It is strongly suggested to use instead of this option the ExtendedMetaData. 
142    * </p>
143    * @see OPTION_EXTENDED_META_DATA
144    */
145   String   OPTION_XML_MAP = "XML_MAP";
146 
147   /**
148    * All EObject references will be uniformly encoded as one or more QName URI pairs,
149    * where the QName is optional depending on whether the referenced object's type is not identicle to that of the feature.
150    */
151   String   OPTION_USE_ENCODED_ATTRIBUTE_STYLE = "USE_ENCODED_ATTRIBUTE_STYLE";
152 
153   /**
154    * Break lines and add indentation to produce a readable document.
155    * The default is <code>Boolean.TRUE</code> unless set to <code>Boolean.FALSE</code> explicitly.
156    */
157   String   OPTION_FORMATTED = "FORMATTED";
158 
159   /**
160    * Attribute formatting that exceeds the specified width will cause a line break
161    * so that formatting will continue indented on the next line.
162    */
163   String   OPTION_LINE_WIDTH = "LINE_WIDTH";
164 
165   /**
166    * Begin a save with this line:
167    * <?xml version="1.0" encoding="encoding"?>
168    */
169   String   OPTION_DECLARE_XML = "DECLARE_XML";
170   
171   /**
172    * Keep default content ( e.g. default attributes). This applies to saving and converting contents to DOM.
173    * By default the default content is discarded.
174    * To save the default content, set this option to <code>Boolean.TRUE</code>.
175    */
176   String   OPTION_KEEP_DEFAULT_CONTENT = "KEEP_DEFAULT_CONTENT";
177   
178   /** 
179    * Save a doctype declaration using systemId and publicId values specified on the resource
180    * @see #getSystemId() 
181    * @see #getPublicId() 
182    * @see #setDoctypeInfo(String,String)
183    *  
184    */
185   String   OPTION_SAVE_DOCTYPE = "SAVE_DOCTYPE";
186   
187   /**
188    * Skip processing for values that contain characters special to XML
189    * Faster for large computer-generated files
190    */
191   String   OPTION_SKIP_ESCAPE  = "SKIP_ESCAPE";
192   
193   /**
194    * Skip escaping special characters, such as '&' char, in URIs during XML serialization.
195    * The default is <code>Boolean.TRUE</code>. To enforce escaping special characters, set this 
196    * option to <code>Boolean.FALSE</code>.
197    */
198   String   OPTION_SKIP_ESCAPE_URI = "SKIP_ESCAPE_URI";
199 
200   /**
201    * This can be one of "THROW", "DISCARD", "RECORD", where "THROW" is the default.
202    */
203   String   OPTION_PROCESS_DANGLING_HREF          = "PROCESS_DANGLING_HREF";
204   String   OPTION_PROCESS_DANGLING_HREF_THROW    = "THROW";
205   String   OPTION_PROCESS_DANGLING_HREF_DISCARD  = "DISCARD";
206   String   OPTION_PROCESS_DANGLING_HREF_RECORD   = "RECORD";
207 
208   /**
209    * This options allows you to record unknown features during deserialization/loading.
210    * The default is <code>Boolean.FALSE</code> unless set to <code>Boolean.TRUE</code> explicitly. 
211    * The unknown featurs and their values can be accessed via getEObjectToExtensionMap().
212    * @see {@link #getEObjectToExtensionMap}  
213    */
214   String   OPTION_RECORD_UNKNOWN_FEATURE = "RECORD_UNKNOWN_FEATURE";
215   
216   /**
217    * Turn this load option on to indicate that a feature should be populated 
218    * from either an attribute or an element even if its feature kind is specified (e.g. element).
219    * The default is <code>Boolean.FALSE</code> unless set to <code>Boolean.TRUE</code> explicitly.
220    */
221   String   OPTION_LAX_FEATURE_PROCESSING = "LAX_FEATURE_PROCESSING";
222 
223   /**
224    * Disable notifications during load, and enable them at the
225    * end of a load.
226    */
227   String   OPTION_DISABLE_NOTIFY = "DISABLE_NOTIFY";
228 
229   /**
230    * Produce an xsi:schemaLocation/xsi:noNamespaceSchemaLocation in the saved result.
231    */
232   String   OPTION_SCHEMA_LOCATION = "SCHEMA_LOCATION";
233 
234   /**
235    * Produce an xsi:schemaLocation/xsi:noNamespaceSchemaLocation in the saved result 
236    * to encode the name of the Java interface that declares the eINSTANCE of the EPackage implementation
237    * for those cases where OPTION_SCHEMA_LOCATION would not produce a physical location URI.
238    */
239   String   OPTION_SCHEMA_LOCATION_IMPLEMENTATION = "SCHEMA_LOCATION_IMPLEMENTATION";
240 
241   /**
242    * Specify the XML encoding to be used during save.
243    */
244   String   OPTION_ENCODING  = "ENCODING";
245   
246   /**
247    * Enable preserving namespace declarations on elements of type <code>AnyType</code>
248    */
249   String   OPTION_RECORD_ANY_TYPE_NAMESPACE_DECLARATIONS  = "RECORD_ANY_TYPE_NAMESPACE_DECLARATIONS";
250 
251   /**
252    * Flush the output stream whenever the number of characters/bytes pending exceeds the specified Integer value. 
253    * This helps to reduce memory requirements for serializing a large file, but it's slower.
254    * The default value is Integer.MAX_VALUE.  
255    * I.e., the stream is never flushed.
256    */
257   String   OPTION_FLUSH_THRESHOLD = "FLUSH_THRESHOLD";
258 
259   /**
260    * Write the intermediate results of serialization to the file system rather to an in-memory buffer.
261    * This helps to reduce memory requirements for serializing a large file, but it's slower.
262    * The default is <code>Boolean.FALSE</code> unless set to <code>Boolean.TRUE</code> explicitly.
263    */
264   String   OPTION_USE_FILE_BUFFER = "USE_FILE_BUFFER";
265 
266   /**
267    * Defer resolution of same document references until the end of the document is reached.
268    */
269   String   OPTION_DEFER_IDREF_RESOLUTION = "DEFER_IDREF_RESOLUTION";
270   
271   /**
272    * Implementations can register the resource handler to receive call backs for loading or saving resources.
273    * The value of this option must be a class that extends the BasicResourceHandler class. 
274    * @see org.eclipse.emf.ecore.xmi.XMLResource.ResourceHandler
275    * @see org.eclipse.emf.ecore.xmi.impl.BasicResourceHandler
276    */
277   String   OPTION_RESOURCE_HANDLER = "RESOURCE_HANDLER";
278 
279   String   HREF = "href";
280   String   NIL = "nil";
281   String   TYPE = "type";
282   String   SCHEMA_LOCATION = "schemaLocation";
283   String   NO_NAMESPACE_SCHEMA_LOCATION = "noNamespaceSchemaLocation";
284 
285   String   XML_NS = ExtendedMetaData.XMLNS_PREFIX;
286   String   XSI_NS = ExtendedMetaData.XSI_PREFIX;
287   String   XSI_URI = ExtendedMetaData.XSI_URI;
288   String   XML_SCHEMA_URI = ExtendedMetaData.XML_SCHEMA_URI;
289 
290   /**
291    * Returns whether the contents will be zipped.
292    */
293   boolean useZip();
294 
295   /**
296    * Set whether the contents will be zipped.
297    */
298   void setUseZip(boolean useZip);
299 
300   /**
301    * Returns the map of options that, in addition to the overriding options specified during save,
302    * are used to to control save behavior.
303    */
304   Map   getDefaultSaveOptions();
305 
306   /**
307    * Returns the map of options that, in addition to the overriding options specified during load,
308    * are used to to control load behavior.
309    */
310   Map   getDefaultLoadOptions();
311 
312   /**
313    * Returns <a HREF='http://www.w3.org/TR/2004/REC-xml-20040204/#NT-PubidLiteral'>public identifier</a> specified on the doctype.
314    */
315   String   getPublicId();
316 
317   /**
318    * Returns <a HREF='http://www.w3.org/TR/2004/REC-xml-20040204/#NT-SystemLiteral'>system identifier</a> specified on the doctype. 
319    */
320   String   getSystemId();
321 
322   /**
323    * Sets the values of <a HREF='http://www.w3.org/TR/2004/REC-xml-20040204/#NT-SystemLiteral'>system</a> and 
324    * <a HREF='http://www.w3.org/TR/2004/REC-xml-20040204/#NT-PubidLiteral'>public</a> identifiers on this resource.
325    * @param publicId
326    * @param systemId
327    */
328   void setDoctypeInfo(String   publicId, String   systemId);
329 
330   /**
331    * Get the XML encoding for this resource. The default is
332    * ASCII.
333    */
334   String   getEncoding();
335 
336   /**
337    * Set the XML encoding for this resource.
338    */
339   void setEncoding(String   encoding);
340 
341   /**
342    * Returns the Map with IDs as keys and EObjects as values.
343    * @deprecated since 2.1.0 This map should not be manipulated directly.  
344    * Use {@link #setID(EObject, String)} and {@link #getID(EObject)} or 
345    * {@link Resource#getEObject(String)} instead.  This method may be removed from
346    * this interface.
347    */
348   Map   getIDToEObjectMap();
349 
350   /**
351    * Returns the Map of EObjects as keys and IDs as values.
352    * @deprecated since 2.1.0 This map should not be manipulated directly.  
353    * Use {@link #setID(EObject, String)} and {@link #getID(EObject)} or 
354    * {@link Resource#getEObject(String)} instead.  This method may be removed from
355    * this interface.
356    */
357   Map   getEObjectToIDMap();
358 
359   /**
360    * Returns the ID that was assigned with {@link #setID(EObject, String)}; if there is
361    * no ID, it returns null.
362    */
363   String   getID(EObject eObject);
364   
365   /**
366    * Sets the ID for the given object. If you are storing the ID
367    * with the object itself, you should override this method.  You can remove the
368    * ID of a given eObject by using <code>null</code> as the id value.
369    */
370   void setID(EObject eObject, String   id);
371 
372   /**
373    * Returns the map with {@link EObject} as keys and corresponding {@link org.eclipse.emf.ecore.xml.type.AnyType}s as the values.
374    * It's used to record unrecognized elements and attributes.
375    */
376   Map   getEObjectToExtensionMap();
377    
378   /**
379    * Create a DOM tree representing contents of this resource.
380    * @param document an empty {@link org.w3c.dom.Document} to use or null. If no document is specified, the 
381    * new {@link org.w3c.dom.Document} will be created using JAXP API.
382    * @param options the "save" options
383    * @param handler the {@link org.eclipse.emf.ecore.xmi.DOMHandler} to record mappings or null. 
384    * If no DOMHandler is passed, the default DOMHandler will be created.
385    * @return the {@link org.w3c.dom.Document}. In the case the document is specified as a parameter, 
386    * the returned document is the same as the one specified, otherwise the newly created document is returned.
387    * @since 2.1.0
388    */
389   Document   save(Document   document, Map   options, DOMHandler handler);
390     
391   /**
392    * Returns the {@link DOMHelper} 
393    * @since 2.1.0
394    */
395   DOMHelper getDOMHelper();
396   
397   /**
398    * Loads the resource from the DOM node, either an Element or Document, using the specified options. 
399    * <p>
400    * This method assumes that no namespace fixup needs to be done.
401    * To process comments and CDATA section nodes, please set XMLResource.OPTION_USE_LEXICAL_HANDLER option to Boolean.TRUE.
402    * </p>
403    * @param node DOM Element or Document node.
404    * @param options the load options.
405    * @see #save(Document, Map, DOMHandler)
406    * @since 2.1.0
407    */
408   void load(Node   node, Map   options) throws IOException  ;
409 
410   /**
411    * This interface represents a mapping from Ecore constructs to the
412    * XML representation of those constructs. It is used by the
413    * XML serializer and deserializer to load and save XML files.
414    */
415   interface XMLMap
416   {
417     /**
418      * Add an XMLInfo object for an Ecore construct to
419      * the map.
420      */
421     void add(ENamedElement element, XMLInfo info);
422 
423     /**
424      * Returns the XMLInfo object for the given Ecore
425      * construct, if there is one.
426      */
427     XMLInfo getInfo(ENamedElement element);
428 
429     /**
430      * Sets the package to use when namespaces are not used in an
431      * XML file; this affects loading only.
432      */
433     void setNoNamespacePackage(EPackage pkg);
434 
435     /**
436      * Gets the package to use when namespaces are not used.
437      */
438     EPackage getNoNamespacePackage();
439 
440     /**
441      * Sets the name of the XML attribute that holds IDs.
442      */
443     void setIDAttributeName(String   name);
444 
445     /**
446      * Gets the name of the XML attribute that holds IDs.
447      */
448     String   getIDAttributeName();
449 
450     /**
451      * Returns the EClassifier with the given namespace URI and
452      * name.
453      */
454     EClassifier getClassifier(String   namespaceURI, String   name);
455 
456     /**
457      * Returns the feature for the given class with the given
458      * namespace URI and name.
459      */
460     EStructuralFeature getFeature(EClass eClass, String   namespaceURI, String   name);
461 
462     /**
463      * Returns the list of features for the given class in the order in which they should be saved.
464      */
465     List   getFeatures(EClass eClass);
466   }
467 
468   /**
469    * This interface is used with the XMLMap interface to describe how
470    * to serialize objects and features. You can specify the name
471    * to use instead of the model name, whether a feature will be
472    * serialized as an XML attribute, XML element, or XML content,
473    * and whether to use a namespace when serializing an object.
474    * <p>
475    * The XMLMap interface maintains the association between XMLInfo
476    * objects and the ecore constructs they describe.
477    */
478   interface XMLInfo
479   {
480     /**
481      * These constants are used to specify the XML representation
482      * of an Ecore construct.
483      */
484     int UNSPECIFIED = -1;
485     int ELEMENT = 0;
486     int ATTRIBUTE = 1;
487     int CONTENT = 2;
488 
489     /**
490      * Returns ELEMENT if the Ecore construct is to be serialized
491      * as an XML element; ATTRIBUTE if the Ecore construct is
492      * to be serialized as an XML attribute; and CONTENT if the
493      * Ecore construct is to be serialized in element content.
494      * By default, the value is UNSPECIFIED.
495      */
496     int getXMLRepresentation();
497 
498     /**
499      * Set attribute to true to serialize a feature as an
500      * XML attribute.
501      */
502     void setXMLRepresentation(int representation);
503 
504     /**
505      * Set the target namespace for the Ecore construct. By
506      * default, this is null. A package with the namespaceURI
507      * must be registered with the EPackage.Registry.
508      */
509     void setTargetNamespace(String   namespaceURI);
510 
511     /**
512      * Gets the target namespace for the Ecore construct.
513      */
514     String   getTargetNamespace();
515 
516     /**
517      * Returns the name to use for the Ecore construct in an
518      * XML file.
519      */
520     String   getName();
521 
522     /**
523      * Set the name to be used in an XML file.
524      */
525     void setName(String   name);
526   }
527 
528   interface ResourceHandler
529   {
530     public void preLoad(XMLResource resource, InputStream   inputStream, Map   options);
531     public void postLoad(XMLResource resource, InputStream   inputStream, Map   options);
532 
533     public void preSave(XMLResource resource, OutputStream   outputStream, Map   options);
534     public void postSave(XMLResource resource, OutputStream   outputStream, Map   options);
535   }
536 
537 }
538
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags