KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > idaremedia > antx > apis > Requester


1 /**
2  * $Id: Requester.java 180 2007-03-15 12:56:38Z ssmc $
3  * Copyright 2004-2005 iDare Media, Inc. All rights reserved.
4  *
5  * Originally written by iDare Media, Inc. for release into the public domain. This
6  * library, source form and binary form, is free software; you can redistribute it and/or
7  * modify it under the terms of the GNU Lesser General Public License (LGPL) as published
8  * by the Free Software Foundation; either version 2.1 of the License, or (at your option)
9  * any later version.<p>
10  *
11  * This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
12  * without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
13  * See the GNU LGPL for more details.<p>
14  *
15  * You should have received a copy of the GNU Lesser General Public License along with this
16  * library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite
17  * 330, Boston, MA 02111-1307 USA. The GNU LGPL can be found online at
18  * http://www.fsf.org/copyleft/lesser.html<p>
19  *
20  * This product has been influenced by several projects within the open-source community.
21  * The JWare developers wish to acknowledge the open-source community's support. For more
22  * information regarding the open-source products used within JWare, please visit the
23  * JWare website.
24  *----------------------------------------------------------------------------------------*
25  * WEBSITE- http://www.jware.info EMAIL- inquiries@jware.info
26  *----------------------------------------------------------------------------------------*
27  **/

28
29 package com.idaremedia.antx.apis;
30
31 import org.apache.tools.ant.Location;
32 import org.apache.tools.ant.Project;
33 import org.apache.tools.ant.ProjectComponent;
34 import org.apache.tools.ant.Target;
35 import org.apache.tools.ant.Task;
36
37 /**
38  * Minimal interaction interface between a generic service and a user of that service.
39  * In this context a "service" is any object that can handle requests from objects
40  * other than itself. This interface allows generic utilities to easily link feedback
41  * and diagnostics trails back to individual users.
42  *
43  * @since JWare/AntX 0.5
44  * @author ssmc, &copy;2004-2005 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
45  * @version 0.5
46  * @.safety n/a
47  * @.group impl,helper
48  **/

49
50 public interface Requester extends ProblemHandler, LogEnabled
51 {
52     /**
53      * Returns a publishable name for the user. Often used in
54      * feedback and/or error messages.
55      * @return name (non-null)
56      */

57     String JavaDoc getName();
58
59
60
61     /**
62      * Returns a usable location for the user. Used solely in
63      * signal generation to link the service user to problems.
64      **/

65     Location getLocation();
66
67
68
69     /**
70      * Returns the project associated with caller. Can return
71      * <i>null</i> if caller is independent of any particular
72      * project (like with utilities).
73      * @return associated project or <i>null</i>
74      **/

75     Project getProject();
76
77
78
79     /**
80      * Returns the (original) script target or <i>null</i> if
81      * this information unknown.
82      **/

83     Target getSourceTarget();
84
85
86
87     /**
88      * An anonymous <em>totally silent</em> service requester proxy.
89      * Unlike an {@linkplain Anonymous} adapter, this requester will
90      * <em>not</em> send messages or indicate problems to the system
91      * consoles.
92      **/

93     public static final Requester DEVNULL= new Requester()
94     {
95         /**
96          * Always returns <span class="src">undefined</span>.
97          **/

98         public String JavaDoc getName() {
99             return "undefined";
100         }
101         /**
102          * Always returns <span class="src">UNKNOWN_LOCATION</span>.
103          **/

104         public Location getLocation() {
105             return Location.UNKNOWN_LOCATION;
106         }
107         /**
108          * Always returns <i>null</i>.
109          **/

110         public Project getProject() {
111             return null;
112         }
113         /**
114          * Always returns <i>null</i> for no source target.
115          **/

116         public Target getSourceTarget() {
117             return null;
118         }
119         /**
120          * Does nothing.
121          **/

122         public void log(String JavaDoc message) {
123         }
124         /**
125          * Does nothing.
126          **/

127         public void log(String JavaDoc message, int msgLevel) {
128         }
129         /**
130          * Does nothing.
131          **/

132         public void problem(Object JavaDoc nugget, int nl) {
133         }
134     };
135
136
137
138
139     /**
140      * An anonymous service requester proxy. Unlike the standard
141      * {@linkplain #DEVNULL null proxy} adapter, anonymous requesters
142      * can specify both a location and an associated project. This is
143      * often the available state from standalone utility methods.
144      * @since JWare/AntX 0.5
145      * @author ssmc, &copy;2004 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
146      * @version 0.5
147      * @.group impl,helper
148      **/

149     public static final class Anonymous extends LogEnabled.ForProject
150         implements Requester
151     {
152         private final Location m_loc;
153
154         /**
155          * Initializes a new anonymous requester.
156          **/

157         public Anonymous() {
158             super(null);
159             m_loc = Location.UNKNOWN_LOCATION;
160         }
161         /**
162          * Initializes a new location-bound anonymous requester.
163          * @param loc caller's location (non-null)
164          **/

165         public Anonymous(Location loc) {
166             super(null);
167             m_loc = loc==null ? Location.UNKNOWN_LOCATION : loc;
168         }
169         /**
170          * Initializes a new location-bound anonymous requester.
171          * @param project caller's associated project (non-null)
172          * @param loc caller's location (non-null)
173          **/

174         public Anonymous(Project project, Location loc) {
175             super(project);
176             m_loc = loc==null ? Location.UNKNOWN_LOCATION : loc;
177         }
178         /**
179          * Always returns <span class="src">undefined</span>.
180          **/

181         public String JavaDoc getName() {
182             return "undefined";
183         }
184         /**
185          * Always returns either <span class="src">UNKNOWN_LOCATION</span>
186          * or a proxy location bound at creation time.
187          **/

188         public Location getLocation() {
189             return m_loc;
190         }
191         /**
192          * Always returns <i>null<i> or the project bound at
193          * creation time.
194          **/

195         public Project getProject() {
196             return getImpl();
197         }
198         /**
199          * Always returns <i>null</i> for no owning target.
200          **/

201         public Target getSourceTarget() {
202             return null;
203         }
204         /**
205          * Records problem using our own log API.
206          **/

207         public void problem(Object JavaDoc nugget, int nl) {
208             log(Tk.stringFrom(nugget,null),nl);
209         }
210     }
211
212
213
214     /**
215      * An anonymous service requester that logs to system consoles.
216      **/

217     public static final Requester ANONYMOUS= new Anonymous();
218
219
220
221     /**
222      * Default {@linkplain Requester} adapter for a standard Ant component.
223      * @since JWare/AntX 0.5
224      * @author ssmc, &copy;2004-2005 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
225      * @version 0.5
226      * @.group impl,helper
227      **/

228     public static class ForComponent extends LogEnabled.ForComponent
229         implements Requester
230     {
231         /**
232          * Initializes a new requester adapter for given component.
233          * @param pc the component being wrapped (non-null)
234          **/

235         public ForComponent(ProjectComponent pc) {
236             super(pc);
237         }
238         /**
239          * Returns component's script-supplied name if possible or
240          * the item's class (leaf) name.
241          **/

242         public String JavaDoc getName() {
243             if (m_PC instanceof Task) {
244                 return ((Task)m_PC).getTaskName();
245             }
246             if (m_PC instanceof Named) {
247                 String JavaDoc n = ((Named)m_PC).getName();
248                 if (n!=null) {
249                     return n;
250                 }
251             }
252             return Tk.leafNameFrom(m_PC.getClass());
253
254         }
255         /**
256          * Returns components assigned parse location or the
257          * <span class="src">UNKNOWN</span> marker if no location
258          * unknown or not defined.
259          * @see ScriptLocatable
260          **/

261         public Location getLocation() {
262             if (m_PC instanceof Task) {
263                 return ((Task)m_PC).getLocation();
264             }
265             if (m_PC instanceof ScriptLocatable) {
266                 return ((ScriptLocatable)m_PC).getLocation();
267             }
268             return Location.UNKNOWN_LOCATION;
269         }
270         /**
271          * Returns compoent's owning target or <i>null</i> if
272          * no such target.
273          **/

274         public Target getSourceTarget() {
275             if (m_PC instanceof Task) {
276                 return ((Task)m_PC).getOwningTarget();
277             }
278             return null;
279         }
280         /**
281          * Always returns task's associated project.
282          **/

283         public Project getProject() {
284             return m_PC.getProject();
285         }
286         /**
287          * Records problem using our own log API.
288          **/

289         public void problem(Object JavaDoc nugget, int nl) {
290             log(Tk.stringFrom(nugget,null),nl);
291         }
292     }
293     
294
295
296
297     /**
298      * Default {@linkplain Requester} adapter for a utility object.
299      * @since JWare/AntX 0.5
300      * @author ssmc, &copy;2004 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
301      * @version 0.5
302      * @.group impl,helper
303      **/

304     public static final class ForUtility extends LogEnabled.ForUtility
305         implements Requester
306     {
307         /**
308          * Initializes a new adapter for given utility.
309          * @param utility the utility being wrapped (non-null)
310          */

311         public ForUtility(ProjectDependent utility) {
312             super(utility);
313         }
314         /**
315          * Always returns leafname of utility's class.
316          **/

317         public String JavaDoc getName() {
318             return Tk.leafNameFrom(getImpl().getClass());
319         }
320         /**
321          * Always returns <span class="src">UNKNOWN_LOCATION</span>
322          * unless the utility implements {@linkplain ScriptLocatable}.
323          **/

324         public Location getLocation() {
325             if (getImpl() instanceof ScriptLocatable) {
326                 return ((ScriptLocatable)getImpl()).getLocation();
327             }
328             return Location.UNKNOWN_LOCATION;
329         }
330         /**
331          * Always returns utility's associated project.
332          **/

333         public Project getProject() {
334             return getImpl().getProject();
335         }
336         /**
337          * Always returns <i>null</i> for no owning target.
338          **/

339         public Target getSourceTarget() {
340             return null;
341         }
342         /**
343          * Records problem using our own log API.
344          **/

345         public void problem(Object JavaDoc nugget, int nl) {
346             log(Tk.stringFrom(nugget,null),nl);
347         }
348     }
349
350
351
352     /**
353      * Default {@linkplain Requester} adapter for a utility object.
354      * @since JWare/AntX 0.5
355      * @author ssmc, &copy;2004 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
356      * @version 0.5
357      * @.group impl,helper
358      **/

359     public static final class ForProject extends LogEnabled.ForProject
360         implements Requester
361     {
362         /**
363          * Initializes a new adapter for a utility method.
364          * @param project the project being wrapped (non-null)
365          */

366         public ForProject(Project project) {
367             super(project);
368         }
369         /**
370          * Always returns the project's name or the empty
371          * string "project".
372          **/

373         public String JavaDoc getName() {
374             Project P = getProject();
375             if (P!=null) {
376                 return P.getName();
377             }
378             return "project";
379         }
380         /**
381          * Always returns <span class="src">UNKNOWN_LOCATION</span>.
382          **/

383         public Location getLocation() {
384             return Location.UNKNOWN_LOCATION;
385         }
386         /**
387          * Always returns associated project.
388          **/

389         public Project getProject() {
390             return getImpl();
391         }
392         /**
393          * Always returns <i>null</i> for no owning target.
394          **/

395         public Target getSourceTarget() {
396             return null;
397         }
398         /**
399          * Records problem using our own log API.
400          **/

401         public void problem(Object JavaDoc nugget, int nl) {
402             log(Tk.stringFrom(nugget,null),nl);
403         }
404     }
405
406
407
408
409     /**
410      * Default {@linkplain Requester} adapter for a compound requester.
411      * A composite requester uses the local helper task's name and
412      * location, but the original source's logging, problem handling, and
413      * project reference.
414      * @since JWare/AntX 0.5
415      * @author ssmc, &copy;2004 <a HREF="http://www.jware.info">iDare&nbsp;Media,&nbsp;Inc.</a>
416      * @version 0.5
417      * @.group impl,helper
418      **/

419 // public static class ForComposite extends LogEnabled.ForComposite
420
// implements Requester
421
// {
422
// private final Task m_task;
423
//
424
// /**
425
// * Initializes a new requester adapter for local helper
426
// * task that is part of a request processing chain.
427
// * @param task the task being wrapped (non-null)
428
// **/
429
// public ForComposite(Task task, Requester source) {
430
// super(source);
431
// m_task = task;
432
// }
433
// /**
434
// * Always returns local task's script-supplied name.
435
// **/
436
// public String getName() {
437
// return getTaskImpl0().getTaskName();
438
// }
439
// /**
440
// * Always returns local task's parse location.
441
// **/
442
// public Location getLocation() {
443
// return getTaskImpl0().getLocation();
444
// }
445
// /**
446
// * Returns the source requester. Never <i>null</i>.
447
// **/
448
// public Requester getRequester0() {
449
// return ((Requester)getLogImpl());
450
// }
451
// /**
452
// * Returns the source's project (not local tasks).
453
// **/
454
// public Project getProject() {
455
// return getRequester0().getProject();
456
// }
457
// /**
458
// * Delegates problem notification to source.
459
// **/
460
// public void problem(Object nugget, int nl) {
461
// getRequester0().problem(nugget,nl);
462
// }
463
// /**
464
// * Returns the local task helper's instance.
465
// **/
466
// public final Task getTaskImpl0() {
467
// return m_task;
468
// }
469
// }
470
}
471
472 /* end-of-Requester.java */
Popular Tags