XMIReferenceResolver


1   /*
2    * The contents of this file are subject to the terms of the Common Development
3    * and Distribution License (the License). You may not use this file except in
4    * compliance with the License.
5    *
6    * You can obtain a copy of the License at http://www.netbeans.org/cddl.html
7    * or http://www.netbeans.org/cddl.txt.
8    *
9    * When distributing Covered Code, include this CDDL Header Notice in each file
10   * and include the License file at http://www.netbeans.org/cddl.txt.
11   * If applicable, add the following below the CDDL Header, with the fields
12   * enclosed by brackets [] replaced by your own identifying information:
13   * "Portions Copyrighted [year] [name of copyright owner]"
14   *
15   * The Original Software is NetBeans. The Initial Developer of the Original
16   * Software is Sun Microsystems, Inc. Portions Copyright 1997-2006 Sun
17   * Microsystems, Inc. All Rights Reserved.
18   */
19  package org.netbeans.api.xmi;
20  
21  import javax.jmi.reflect.RefObject;
22  import javax.jmi.reflect.RefPackage;
23  import java.util.Collection  ;
24  import javax.jmi.xmi.MalformedXMIException;
25  import java.io.IOException  ;
26  
27  /** Implementation of this interface can be passed to XMI reader/consumer
28   * (using {@link XMIInputConfig#setReferenceResolver} method) to enable custom resolving of hrefs.
29   * If an XMIReferenceResolver is registered for an XMI consumer, the XMI consumer will call
30   * {@link #register} for each object that it successfuly deserialized from the XMI file.
31   * At the end of the document the XMI consumer will call {@link #resolve} passing all the
32   * hrefs found in the document and an object that implements {@link XMIReferenceResolver.Client}
33   * to receive callbacks.
34   * Implementation of XMIReferenceResolver should try to
35   * resolve these hrefs and make callbacks to the passed client (by calling
36   * {@link XMIReferenceResolver.Client#resolvedReference}) for each resolved href.<p>
37   * Note, that in some obscure cases, the XMI consumer may call {@link #register} method
38   * even during the execution of {@link XMIReferenceResolver.Client#resolvedReference} method 
39   * in case when XMI consumer had to postpone creation of some object because of unresolved 
40   * reference to an object within an attribute (i.e. if an unresolved object was part of 
41   * an attribute value).
42   * <i>IMPORTANT: During the whole XMI reading, the XMI consumer should
43   * hold a lock on the used XMIReferenceResolver instance to avoid concurrency problems.</i>
44   *
45   * @author Martin Matula
46   * @author Daniel Prusa
47   */
48  public interface XMIReferenceResolver {
49      /** Registers an object that can be resolved. This method should be called by
50       * XMI consumer each time it successfuly deserializes an object from XMI, given that the object
51       * was assigned an xmiId (for objects that do not have xmiId defined in XMI file
52       * this method should not be called).<p>
53       * Implementation of this interface should remember all the registered objects and
54       * use them for resolving hrefs.
55       * @param systemId URI of the document that called this method (the URI is essential for
56       * correct resolution of cyclic and relative references).
57       * @param xmiId XMI ID of the object deserialized from XMI. If XMI ID for the object
58       * is not available, this method should not be called.
59       * @param object Object deserialized from XMI.
60       */
61      public void register(String   systemId, String   xmiId, RefObject object);
62      
63      /**
64       * Resolves external references and calls 
65       * {@link XMIReferenceResolver.Client#resolvedReference} for each.
66       * Before returning from this method (only in case of outermost call to it - i.e. this
67       * does not hold for nested recursive calls from XMI consumers created from within this
68       * method) the instance of this class should be restored to its initial state (all
69       * registered references should be forgotten).
70       *
71       * @param client Implementation of callback method used for reference resolving notifications.
72       * @param extent Target package (for resolved objects).
73       * @param systemId URI of the document where href is used. This parameter is provided only 
74       * if it is known by XMI consumer, otherwise <code>null</code> is passed.
75       * @param configuration Configuration to be used for XMI consumer used for reading 
76       * external XMI document to resolve the href (if needed).
77       * @param hrefs References to be resolved.
78       *
79       * @throws MalformedXMIException Thrown
80       * to indicate an error (element cannot be resolved, etc.)
81       * @throws IOException I/O error during XMI reading.
82       */
83      public void resolve(Client client, RefPackage extent, String   systemId, XMIInputConfig configuration, Collection   hrefs) throws MalformedXMIException, IOException  ;
84      
85      public interface Client {
86          /** Method called by reference resolver for each href resolved during the call
87           * to {@link XMIReferenceResolver#resolve}.
88           * @param href Resolved reference.
89           * @param object Object that the reference was resolved to.
90           */
91          public void resolvedReference(String   href, RefObject object);
92      }
93  }
94
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags