XMLHelper


1   /**
2    * <copyright>
3    *
4    * Copyright (c) 2002-2004 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: XMLHelper.java,v 1.10 2005/06/08 06:16:07 nickb Exp $
16   */
17  package org.eclipse.emf.ecore.xmi;
18  
19  import java.util.List  ;
20  import java.util.Map  ;
21  
22  import org.eclipse.emf.common.util.EMap;
23  import org.eclipse.emf.common.util.URI;
24  import org.eclipse.emf.ecore.EClass;
25  import org.eclipse.emf.ecore.EDataType;
26  import org.eclipse.emf.ecore.EFactory;
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.util.ExtendedMetaData;
32  
33  /**
34   * Configuration class for XML. It holds the EPackage to
35   * use when XML namespaces are not used in an XML file. It also
36   * holds the XMLMap to be used when serializing an XML file.
37   * The XML deserializer and serializer uses this class when
38   * an XML file is loaded and saved.
39   */
40  public interface XMLHelper
41  {
42    /**
43     * Sets various resource options on the helper
44     */
45    public void setOptions(Map   options);
46    
47    /**
48     * Sets the package to use when there is no XML namespace in an XML
49     * file.
50     */
51    public void setNoNamespacePackage(EPackage pkg);
52  
53    /**
54     * Gets the package to use when there is no XML namespace in an
55     * XML file.
56     */
57    public EPackage getNoNamespacePackage();
58    
59    /**
60     * Sets the any simple type class.
61     * @see XMLResource#OPTION_ANY_SIMPLE_TYPE
62     */
63    public void setAnySimpleType(EClass type);
64  
65    /**
66     * Sets the XMLMap to use when serializing an XML file.
67     */
68    public void setXMLMap(XMLResource.XMLMap map);
69  
70    /**
71     * Gets the XMLMap to use when serializing an XML file.
72     */
73    public XMLResource.XMLMap getXMLMap();
74  
75    /**
76     * Sets the ExtendedMetaData to use when serializing an XML file.
77     */
78    public void setExtendedMetaData(ExtendedMetaData extendedMetaData);
79  
80    /**
81     * Gets the ExtendedMetaData to use when serializing an XML file.
82     */
83    public ExtendedMetaData getExtendedMetaData();
84  
85    /**
86     * Returns the resource
87     */
88    XMLResource getResource();
89  
90    /**
91     * Returns the XMI value of the EObject's feature
92     */
93    Object   getValue(EObject eObject, EStructuralFeature eStructuralFeature);
94  
95    /**
96     * Returns the XML name of the ENamedElement
97     */
98    String   getName(ENamedElement eNamedElement);
99  
100   /**
101    * Returns the nsName:name
102    *  c.ePackage().nsName() :
103    *  c.eName()
104    *
105    * If there is an XMLMap, and the target namespace is null
106    * for this eClass, just the name is returned. If the map
107    * has a target namespace specified, that target namespace is
108    * used rather than the namespace from the EPackage.
109    */
110   String   getQName(EClass eClass);
111 
112   /**
113    * This method populates the given {@link NameInfo} with name information, resetting all the current
114    * values in the <tt>nameInfo</tt>
115    * @param nameInfo the name information to populate
116    * @param eClass the EClass for which name has to be computed
117    * @see XMLHelper#getQName(EClass)
118    * @since 2.1.0
119    */
120   void populateNameInfo(NameInfo nameInfo, EClass eClass);
121 
122   /**
123    * Returns the nsName:name
124    *  c.ePackage().nsName() :
125    *  c.eName()
126    *
127    * If there is an XMLMap, and the target namespace is null
128    * for this eClass, just the name is returned. If the map
129    * has a target namespace specified, that target namespace is
130    * used rather than the namespace from the EPackage.
131    */
132   String   getQName(EDataType eDataType);
133   
134   /**
135    * This method populates the given {@link NameInfo} with name information, resetting all the current
136    * values in the <tt>nameInfo</tt>
137    * @param nameInfo the name information to fill in
138    * @param eDataType the EDataType for which name has to be computed
139    * @see XMLHelper#getQName(EDataType)
140    * @since 2.1.0
141    */
142   void populateNameInfo(NameInfo nameInfo, EDataType eDataType);
143 
144   /**
145    * By default, this method returns the name of the feature.
146    * However, if there is an XMLMap, and the map specifies a
147    * target namespace, the nsPrefix:name is returned.
148    */
149   String   getQName(EStructuralFeature feature);
150 
151   /**
152    * This method populates the given {@link NameInfo} with name information, resetting all the current
153    * values in the <tt>nameInfo</tt> 
154    * @param nameInfo the name information to fill in
155    * @param feature the EStructuralFeature for which name has to be computed
156    * @see #getQName(EStructuralFeature)
157    * @since 2.1.0
158    */
159   void populateNameInfo(NameInfo nameInfo, EStructuralFeature feature);
160 
161   /**
162    * Return the prefix used for this package.
163    */
164   String   getPrefix(EPackage ePackage);
165 
166   /**
167    * Returns the namespaceURI in scope for the prefix.
168    */
169   String   getNamespaceURI(String   prefix);
170 
171   /**
172    * Return all the prefixes used for this package.
173    */
174   List   getPrefixes(EPackage ePackage);
175 
176   /**
177    * Returns the xmi:id or null to supress
178    */
179   String   getID(EObject eObject);
180 
181   /**
182    * Returns an IDREF to this object
183    */
184   String   getIDREF(EObject eObject);
185 
186   /**
187    * Returns an HREF to this object from this resource
188    */
189   String   getHREF(EObject eObject);
190 
191   /**
192    * Returns a relative URI if necessary and if possible.
193    */
194   URI deresolve(URI uri);
195 
196   /**
197    * Returns the packages in getQName()
198    */
199   EPackage[] packages();
200 
201   /**
202    * Create an object given an EFactory and a type name.
203    */
204   EObject createObject(EFactory eFactory, String   name);
205 
206   /**
207    * Set the value of the feature for the object.
208    */
209   void setValue(EObject eObject, EStructuralFeature eStructuralFeature, Object   value, int position);
210 
211   /**
212    * Returns the structural feature for the XML element/attribute with the given namespaceURI and name.
213    */
214   EStructuralFeature getFeature(EClass eClass, String   namespaceURI, String   name);
215 
216   /**
217    * Returns the structural feature for the XML element/attribute with the given namespaceURI and name.
218    */
219   EStructuralFeature getFeature(EClass eClass, String   namespaceURI, String   name, boolean isElement);
220 
221   /**
222    * These are the kinds of features that are important
223    * when loading XMI files.
224    */
225   int DATATYPE_SINGLE = 1;
226   int DATATYPE_IS_MANY = 2;
227   int IS_MANY_ADD = 3;
228   int IS_MANY_MOVE = 4;
229   int OTHER = 5;
230 
231   /**
232    * Return the kind of feature.
233    */
234   int getFeatureKind(EStructuralFeature feature);
235 
236   /**
237    * Return an XML encoding corresponding to the given Java encoding.
238    * By default, the Java encoding is returned.
239    */
240   String   getXMLEncoding(String   javaEncoding);
241 
242   /**
243    * Return a Java encoding corresponding to the given XML encoding.
244    * By default, the XML encoding is returned.
245    */
246   String   getJavaEncoding(String   xmlEncoding);
247 
248   interface ManyReference
249   {
250     EObject getObject();
251     EStructuralFeature getFeature();
252     Object  [] getValues();
253     int[] getPositions();
254     int getLineNumber();
255     int getColumnNumber();
256   }
257 
258   List   setManyReference(ManyReference reference, String   location);
259 
260   void setCheckForDuplicates(boolean checkForDuplicates);
261   
262   void setProcessDanglingHREF(String   value);
263 
264   DanglingHREFException getDanglingHREFException();
265 
266   URI resolve(URI relative, URI base);
267   
268   /** 
269    * Records the prefix to URI mapping while loading an XML document.
270    */
271   void addPrefix(String   prefix, String   uri);
272   
273   /**
274    * Returns a map of prefixes to URI mapping for elements with any content
275    */
276   Map   getAnyContentPrefixToURIMapping();
277   
278   /**
279    * Must be called during endDocument to record all the prefix to URI mappings that have
280    * been seen in the document during loading
281    */
282   void recordPrefixToURIMapping();
283   
284   /** 
285    * Returns the namespace prefix that's in effect while loading an XML document.
286    */
287   String   getURI(String   prefix);
288 
289   /**
290    * Starts a new namespace context while loading an XML document.
291    * <p>
292    * A new context should be pushed at the beginning of each XML element.
293    * The new context will automatically inherit the declarations of its parent context, 
294    * but it will also keep track of which declarations were made within this context.
295    * </p>
296    */
297   public void pushContext();
298 
299   /**
300    * Reverts to the previous namespace context while loading XML document.
301    * <p>
302    * The context should be popped at the end of each XML element.  
303    * After popping the context, all namespace prefix mappings that were previously in scope are restored.
304    * </p>
305    */
306   public void popContext();
307   
308   /** 
309    * Converts the given valuevalue to string while saving an XML document. 
310    */
311   public String   convertToString(EFactory factory, EDataType dataType, Object   data);
312 
313   EMap getPrefixToNamespaceMap();
314   void setPrefixToNamespaceMap(EMap prefixToNamespaceMap);
315   
316   /**
317    * Specify if qualified names must have a prefix or could use default namespace (if possible)
318    * @param mustHavePrefix
319    */
320   void setMustHavePrefix(boolean mustHavePrefix);
321 
322 }
323
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags