1 /*
2 * $Id$
3 *
4 * Copyright (c) 2010, 2012 Oracle and/or its affiliates. All rights reserved.
5 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
6 *
7 * This code is free software; you can redistribute it and/or modify it
8 * under the terms of the GNU General Public License version 2 only, as
9 * published by the Free Software Foundation. Oracle designates this
10 * particular file as subject to the "Classpath" exception as provided
11 * by Oracle in the LICENSE file that accompanied this code.
12 *
13 * This code is distributed in the hope that it will be useful, but WITHOUT
14 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
15 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
16 * version 2 for more details (a copy is included in the LICENSE file that
17 * accompanied this code).
18 *
19 * You should have received a copy of the GNU General Public License version
20 * 2 along with this work; if not, write to the Free Software Foundation,
21 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
22 *
23 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
24 * or visit www.oracle.com if you need additional information or have any
25 * questions.
26 */
27
28 package com.sun.javatest.exec;
29
30 import com.sun.javatest.Parameters;
31 import java.util.List;
32 import java.util.Map;
33
34 /**
35 * An interface that encapsulates all properties required to run tests.
36 * It's introduced to make it possible to get rid of such monsters as
37 * InterviewParameters, Template and WorkDir.
38 *
39 * It's assumed that components will communicate Session via Update and Event
40 * classes: those components which are aware how to modify the config
41 * will apply some Update object to the config, the config in its turn will
42 * send to all registered observers the corresponding Event object.
43 *
44 * <b>Important note:</b> JavaTest is not ready yet to operate with Session
45 * instances, therefore one should implement the SessionExt interface or extends
46 * BasicSession class to provide its own behavior.
47 *
48 * @see SessionExt
49 * @see BasicSession
50 */
51 public interface Session {
52 // Currently in
53 // the com.sun.javatest.exec package, but in the future it's better to
54 // find more appropriate place for it.
55
56 /**
57 * Exception signaling of the problem happened while dealing with Session.
58 */
59 public class Fault extends Exception {
60 public Fault(String reason) {
61 super(reason);
62 }
63 public Fault(Throwable thr) {
64 super(thr);
65 }
66 }
67
68 /**
69 * Root interface for all updates to Session.
70 */
71 public interface Update { }
72
73 /**
74 * Root interface for all events happened when state of Session changed.
75 */
76 public interface Event { }
77
78
79 /**
80 * Interface for observers of the Session state.
81 */
82 public interface Observer {
83 /**
84 * Invoked when state of config has changed
85 * @param ev - Event describing the change
86 */
87 void updated(Event ev);
88 }
89
90 /**
91 * Method to be invoked from outside to change the state of the Session.
92 * @param u - object encapsulating data describing the change.
93 * @throws com.sun.javatest.exec.Session.Fault in case of any problem
94 */
95 public void update(Update u) throws Fault;
96
97 /**
98 * Method to be invoked from outside to change the state of the Session.
99 * @param u - object encapsulating data describing the change.
100 * @param updateConfig - hint whether to reload the configuration from disk
101 * @throws com.sun.javatest.exec.Session.Fault in case of any problem
102 * @since 4.4.1
103 */
104 public void update(Update u, boolean updateConfig) throws Fault;
105
106 /**
107 * Registers the observer. Does nothing if the observer is null or already
108 * registered.
109 * @param obs - observer
110 */
111 public void addObserver(Observer obs);
112
113 /**
114 * Unregisters the observer. Does nothing if the observer is null or not
115 * registered.
116 * @param obs - observer
117 */
118 public void removeObserver(Observer obs);
119
120 /**
121 * Delivers events to the all registered observers
122 * @param evn - event to be sent out.
123 */
124 public void notifyObservers(Event evn);
125
126 /**
127 * Gets test filter by its name.
128 * @param name - should be from the list of supported names.
129 * @return desired filter, if found
130 * @throw new IllegalArgumentException if name is null or unknown.
131 * @see getTestFilterNames
132 */
133 //public TestFilter getTestFilter(String name);
134
135 /**
136 * @return list of names of supported test filters.
137 */
138 //public List<String> getTestFilterNames();
139
140 /**
141 * Saves the config state to the file
142 * @param file destination file
143 * @throws com.sun.javatest.exec.Session.Fault
144 */
145 //public void save(File file) throws Fault;
146
147 /**
148 * Saves the config state to the map
149 * @param map
150 * @throws com.sun.javatest.exec.Session.Fault
151 */
152 public void save(Map<String, String> map);
153
154
155 /**
156 * Restores the config state from the file
157 * @param file - source file
158 * @throws com.sun.javatest.exec.Session.Fault
159 */
160 //public void restore(File file) throws Fault;
161
162 /**
163 * Restores the config state from the map
164 * @param map
165 * @throws com.sun.javatest.exec.Session.Fault
166 */
167 public void restore(Map map) throws Fault;
168
169 /**
170 * Disposes configuration. Critical when heavy objects were used.
171 */
172 public void dispose();
173
174 /**
175 * Returns the config property names
176 * @return Configuration property name List
177 */
178 public List<String> getPropertyNames();
179
180 /**
181 * @return the value of property or null if unset
182 * @throws IllegalArgumentException if case of unknown name
183 * @see #getPropertyNames
184 */
185 public String getValue(String name);
186
187 /**
188 * @return true if configuration is ready for test execution
189 */
190 public boolean isReady();
191
192 /**
193 * Data required to execute tests.
194 * In future - should be replaced.
195 * @return The current parameters in use.
196 */
197 public Parameters getParameters();
198
199 }