001 /*
002 * Copyright 2004-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.component;
020
021 import java.rmi.Remote;
022 import java.rmi.RemoteException;
023 import java.lang.reflect.InvocationTargetException;
024
025 import net.dpml.state.State;
026 import net.dpml.state.StateListener;
027 import net.dpml.state.UnknownOperationException;
028 import net.dpml.state.UnknownTransitionException;
029
030 /**
031 * Provider holder.
032 *
033 * @author <a href="http://www.dpml.net">Digital Product Meta Library</a>
034 * @version 1.2.0
035 */
036 public interface Provider extends Remote, Commissionable
037 {
038 /**
039 * Return a parent provider.
040 * @return the parent provider or null if this is a root provider
041 * @exception RemoteException if a remote I/O occurs
042 */
043 Provider getParent() throws RemoteException;
044
045 /**
046 * Return the current status of the provider.
047 * @return the provider status
048 * @exception RemoteException if a remote I/O occurs
049 */
050 Status getStatus() throws RemoteException;
051
052 /**
053 * Return a provider capable of supporting the requested service.
054 * @param service the service descriptor
055 * @return a component matching the requested service
056 * @exception ServiceNotFoundException if no component could found
057 * @exception RemoteException if a remote I/O occurs
058 */
059 Provider lookup( Service service ) throws ServiceNotFoundException, RemoteException;
060
061 /**
062 * Returns the current state of the control.
063 * @return the current runtime state
064 * @exception RemoteException if a remote I/O error occurs
065 */
066 State getState() throws RemoteException;
067
068 /**
069 * Add a state listener to the control.
070 * @param listener the state listener
071 * @exception RemoteException if a remote I/O error occurs
072 */
073 void addStateListener( StateListener listener ) throws RemoteException;
074
075 /**
076 * Remove a state listener from the control.
077 * @param listener the state listener
078 * @exception RemoteException if a remote I/O error occurs
079 */
080 void removeStateListener( StateListener listener ) throws RemoteException;
081
082 /**
083 * Return the runtime value associated with this instance.
084 * @param isolate if TRUE the value returned is a proxy exposing the
085 * service interfaces declared by the component type otherwise
086 * the instance value is returned.
087 * @return the value
088 * @exception RemoteException if a remote I/O error occurs
089 */
090 Object getValue( boolean isolate ) throws RemoteException;
091
092 /**
093 * Apply a transition to the instance.
094 * @param key the transition name
095 * @return the state established as a result of applying the transition
096 * @exception UnknownTransitionException if the supplied key does not map to an available transition
097 * @exception InvocationTargetException if an invocation error occurs
098 * @exception RemoteException if a remote I/O error occurs
099 */
100 State apply( String key )
101 throws UnknownTransitionException, InvocationTargetException, RemoteException;
102
103 /**
104 * Invoke an operation on the instance.
105 * @param name the operation name
106 * @param args operation arguments
107 * @return the result of the operation invocation
108 * @exception UnknownOperationException if the supplied key does not map to an available operation
109 * @exception InvocationTargetException if an invocation error occurs
110 * @exception RemoteException if a remote I/O error occurs
111 */
112 Object exec( String name, Object[] args )
113 throws UnknownOperationException, InvocationTargetException, RemoteException;
114
115 /**
116 * Invoke an operation on the instance.
117 * @param method the operation name
118 * @param args operation arguments
119 * @return the result of the operation invocation
120 * @exception UnknownOperationException if the supplied key does not map to an available operation
121 * @exception InvocationTargetException if an invocation error occurs
122 * @exception IllegalStateException if the component state does not expose the operation
123 * @exception RemoteException if a remote I/O error occurs
124 */
125 Object invoke( String method, Object[] args )
126 throws UnknownOperationException, InvocationTargetException,
127 IllegalStateException, RemoteException;
128
129 }