001    /*
002     * Copyright 2005-2006 Stephen J. McConnell.
003     *
004     * Licensed  under the  Apache License,  Version 2.0  (the "License");
005     * you may not use  this file  except in  compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     *   http://www.apache.org/licenses/LICENSE-2.0
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed  under the  License is distributed on an "AS IS" BASIS,
012     * WITHOUT  WARRANTIES OR CONDITIONS  OF ANY KIND, either  express  or
013     * implied.
014     *
015     * See the License for the specific language governing permissions and
016     * limitations under the License.
017     */
018    
019    package net.dpml.metro;
020    
021    import java.rmi.Remote;
022    import java.rmi.RemoteException;
023    
024    import net.dpml.metro.info.EntryDescriptor;
025    import net.dpml.metro.info.PartReference;
026    
027    import net.dpml.component.Directive;
028    
029    import net.dpml.lang.UnknownKeyException;
030    
031    
032    /**
033     * The ContextModel interface defines the remotely accessible component context. 
034     *
035     * @author <a href="http://www.dpml.net">Digital Product Meta Library</a>
036     * @version 1.2.0
037     */
038    public interface ContextModel extends Remote
039    {
040       /**
041        * Return the set of context entries descriptors.
042        *
043        * @return context entry descriptor array
044        * @exception RemoteException if a remote exception occurs
045        */
046        EntryDescriptor[] getEntryDescriptors() throws RemoteException;
047        
048       /**
049        * Return  a of context entry descriptor.
050        *
051        * @param key the entry key
052        * @return the entry descriptor
053        * @exception UnknownKeyException if the key is unknown
054        * @exception RemoteException if a remote exception occurs
055        */
056        EntryDescriptor getEntryDescriptor( String key ) throws UnknownKeyException, RemoteException;
057        
058       /**
059        * Return the current directive assigned to a context entry.
060        * @param key the context entry key
061        * @return the directive
062        * @exception UnknownKeyException if the key is unknown
063        * @exception RemoteException if a remote exception occurs
064        */
065        Directive getEntryDirective( String key ) throws UnknownKeyException, RemoteException;
066    
067       /**
068        * Validate the model.
069        * @exception ValidationException if one or more issues exist within the model
070        * @exception RemoteException if a remote exception occurs
071        */
072        void validate() throws ValidationException, RemoteException;
073    
074       /**
075        * Set a context entry directive value.
076        * @param key the context entry key
077        * @param directive the context entry directive
078        * @exception UnknownKeyException if the key is unknown
079        * @exception RemoteException if a remote I/O error occurs
080        */
081        void setEntryDirective( String key, Directive directive ) 
082          throws UnknownKeyException, RemoteException;
083        
084       /**
085        * Apply an array of tagged directive as an atomic operation.  Application of 
086        * directives to the context model is atomic such that changes are applied under an 
087        * 'all-or-nothing' policy.
088        *
089        * @param directives an array of part references
090        * @exception UnknownKeyException if a key within the array does not match a 
091        *     key within the context model.
092        * @exception RemoteException if a remote I/O error occurs
093        */
094        void setEntryDirectives( PartReference[] directives ) 
095          throws UnknownKeyException, RemoteException;
096    
097    }