MDRepository


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.mdr;
20  
21  import javax.jmi.reflect.*;
22  import org.netbeans.api.mdr.events.MDRChangeSource;
23  
24  /** Interface for accessing content of a metadata repository.
25   *
26   * @author Martin Matula
27   * @version 0.4
28   */
29  public interface MDRepository extends MDRChangeSource {
30      /** Instantiates MOF Model package.
31       * @param substName name (unique within the repository) for the new MOF package extent
32       * @throws CreationFailedException instantiation of the package failed (e.g. if an extent with a given name already exists)
33       * @return reference to the created package extent
34       */
35      public RefPackage createExtent(String   substName) throws CreationFailedException;
36      
37      /** Instantiates given package.
38       * If the package that has to be instantiated clusters some other packages, these clustered packages will be instantiated
39       * automatically but they will be not associated with any names so they will not be accessible directly. If the instantiated package will be deleted,
40       * the automatically created extents will also be deleted (if there are no other references to them).
41       * @param substName name (unique within the repository) for the new package extent
42       * @param metaPackage reference to the package that should be instantiated
43       * @throws CreationFailedException instantiation of the package failed (e.g. if an extent with a given name already exists)
44       * @return reference to the created extent
45       */
46      public RefPackage createExtent(String   substName, RefObject metaPackage) throws CreationFailedException;
47      
48      /** Instantiates given package.
49       * If the package that is to be instantiated clusters some other packages, repository will use a corresponding existing package extent passed
50       * in existingExtents parameter for clustering. If an instance of some particular package cannot be found in existingExtents paramter, it
51       * will be automatically created (this instance will not have any name and thus it won't be accessible directly;
52       * once none of existing extents will cluster it, it should be deleted automatically).
53       * @param substName name (unique within the repository) for the new package extent
54       * @param metaPackage reference to the package that should be instantiated
55       * @param existingInstances existing package extents that will be used instead of creating a new extent if a package is clustered
56       * @throws CreationFailedException instantiation of the package failed (e.g. if an extent with a given name already exists)
57       * @return reference to the created extent
58       */
59      public RefPackage createExtent(String   substName, RefObject metaPackage, RefPackage existingInstances[]) throws CreationFailedException;
60  
61      /** Returns reference to a package extent of a given name.
62       * @param name name of the package extent to be returned
63       * @return reference to the package extent (returns null if extent of a given name was not found)
64       */
65      public RefPackage getExtent(String   name);
66      
67      /** Returns names for all named package extents in the repository.
68       * @return Array of extent names.
69       */
70      public String  [] getExtentNames();
71  
72      /**
73       * Returns the object with the given MOF ID.
74       *
75       * @param mofId the MOF ID of the object to be returned
76       * @return the object with the given MOF ID or <code>null</code> if no such object is found
77       * 
78       * 
79       */
80      public RefBaseObject getByMofId(String   mofId);
81      
82      /** Starts a new transaction. This method causes that the repository will be locked
83       * for read-only access or exclusive write access (depending on the value passed as
84       * a parameter) and starts a new transaction. It is prefered to enclose any batch
85       * operations on MDR by <code>beginTrans</code> and <code>endTrans</code> calls
86       * to avoid autocommiting (which may be slow) after each JMI operation.<p>
87       * Transactions can be nested however real nested transaction commit/rollback
88       * does not need to be implemented - implementation can commit/rollback whole transaction
89       * after the outermost <code>endTrans</code> call depending on whether any nested
90       * transaction failed.<p>
91       * During each transaction it is guaranteed that no other thread can
92       * modify the metadata.<p>
93       * <i>Important:</i>This call locks the repository and the lock is held till the
94       * transaction is ended by a call to <code>endTrans</code>. To make sure there is
95       * a corresponding <code>endTrans</code> call to each <code>beginTrans</code> call
96       * use the <code>try-finally</code> construct:<p>
97       * <code>
98       * beginTrans(false);<br>
99       * try {<br>
100      * &nbsp;&nbsp;&nbsp;&nbsp;// set of JMI calls<br>
101      * } finally {<br>
102      * &nbsp;&nbsp;&nbsp;&nbsp;endTrans();<br>
103      * }
104      * </code>
105      * @param writeAccess <code>true</code> indicates that the transaction will be
106      *  modifying the repository. <code>false</code> means the transaction is
107      *  read-only (it will not be allowed to modify any data). Transactions with
108      *  write access cannot be nested into read-only transactions.
109      */
110     public void beginTrans(boolean writeAccess);
111     
112     /** Ends transaction started by <code>beginTrans</code> call. If the transaction
113      * modified some data, this call will attemp to commit it.<p>
114      * This method has the same effect as calling <code>endTrans(false)</code>.
115      */
116     public void endTrans();
117     
118     /** Ends transaction started by <code>beginTrans</code> call.
119      * Result of this call depends on whether it is nested in another
120      * <code>beginTrans</code> - <code>endTrans</code> pair or not.
121      * If this call is nested and value of <code>rollback</code> parameter is
122      * <code>false</code>, it will not affect the result of the <code>endTrans</code>
123      * call corresponding to the outermost call to <code>beginTrans</code>. However
124      * if <code>true</code> is passed, the whole transaction will be rolled back by
125      * the last (i.e. outermost) <code>endTrans</code> call (no matter what will be the
126      * value of <code>rollback</code> parameter for this last call).
127      * If this call is not nested (i.e. it is outermost) the whole transaction is
128      * commited if <code>false</code> was passed to this call and all the nested
129      * <code>endTrans</code> calls. Otherwise (if <code>true</code> was passed to this
130      * call or any nested <code>endTrans</code> call) the transaction is rolled back.
131      */
132     public void endTrans(boolean rollback);
133     
134     /** Shuts down the repository. This method should be called from {@link MDRManager#shutdownAll} method.
135      * Implementation of this method should do all the necessary clean-up actions,
136      * such as flushing storage caches, etc.
137      */
138     public void shutdown();
139 }
140
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags