1 <!--
2 * Copyright (c) 2007, 2017 Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation.
8 *
9 * This code is distributed in the hope that it will be useful, but WITHOUT
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
12 * version 2 for more details (a copy is included in the LICENSE file that
13 * accompanied this code).
14 *
15 * You should have received a copy of the GNU General Public License version
16 * 2 along with this work; if not, write to the Free Software Foundation,
17 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
18 *
19 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
20 * or visit www.oracle.com if you need additional information or have any
21 * questions.
22 -->
23 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
24 <HTML>
25 <HEAD>
26 <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8">
27 <TITLE>Jemmy lookup principles</TITLE>
28 <META NAME="GENERATOR" CONTENT="OpenOffice.org 2.4 (Unix)">
29 <META NAME="CREATED" CONTENT="0;0">
30 <META NAME="CHANGEDBY" CONTENT="Alexandre Iline">
31 <META NAME="CHANGED" CONTENT="20090501;17335200">
32 <STYLE TYPE="text/css">
33 <!--
34 @page { size: 8.5in 11in }
35 H2.western { font-family: "Albany", sans-serif; font-size: 14pt; font-style: italic }
36 H2.cjk { font-family: "HG Mincho Light J"; font-size: 14pt; font-style: italic }
37 H2.ctl { font-family: "Arial Unicode MS"; font-size: 14pt; font-style: italic }
38 H3.western { font-family: "Albany", sans-serif }
39 H3.cjk { font-family: "HG Mincho Light J" }
40 H3.ctl { font-family: "Arial Unicode MS" }
41 -->
42 </STYLE>
43 </HEAD>
44 <BODY LANG="en-US" DIR="LTR">
45 <H1>Jemmy lookup principles</H1>
46 <P>The document describes principles of Jemmy lookup API. Such
47 principles are the same for any extension built on <CODE>JemmyCore</CODE>
48 for any particular component library. The idea here is to provide
49 searching capabilities so that
50 </P>
51 <UL>
52 <LI><P STYLE="margin-bottom: 0in">Any possible criteria could be
53 used
54 </P>
55 <LI><P STYLE="margin-bottom: 0in">Any number or criteria could be
56 used consequently
57 </P>
58 <LI><P STYLE="margin-bottom: 0in">Access both to control instance
59 and a wrapper instance is provided
60 </P>
61 <LI><P>No costing needed
62 </P>
63 </UL>
64 <H2 CLASS="western">Search criteria</H2>
65 <P>Search criteria specified by implementing <CODE>LookupCriteria</CODE>
66 interface. There are several implementations of the criteria in
67 <CODE>JemmyCore</CODE> which are abstract.
68 </P>
69 <P><I>Example</I>:
70 </P>
71 <PRE> public class ByTextSearch<T extends JTextComponent> implements LookupCriteria<T> {
72 String text;
73 public ByTextSearch(String text) {
74 this.text = text;
75 }
76 public boolean check(T control) {
77 return control.getText().equals(text);
78 }
79 }
80 </PRE><P>
81 Naturally, any kind of custom search criteria could be specified my
82 creating an implementation if the interface.
83 </P>
84 <H2 CLASS="western">Search functionality</H2>
85 <H3 CLASS="western">Parent</H3>
86 <P><CODE>Parent</CODE> interface represents the start point for a component
87 lookup. Parent could be a</P>
88 <UL>
89 <LI><P>root of control hierarchy (<CODE>Stage</CODE> or <CODE>Scene</CODE> in JavaFX)</P>
90 <LI><P>A container in the middle (such as <CODE>Frame</CODE> in AWT)</P>
91 </UL>
92 <P>from the lookup perspective, parent only is able to get an access
93 to a <CODE>Lookup</CODE> imstance.</P>
94 <H3 CLASS="western">Lookup</H3>
95 <P>The search capabilities are presented by <CODE>Lookup</CODE>
96 interface. Most importantly the interface defines methods to narrow
97 the search with another search criteria and optionally control type,
98 which (the methods) return an instance on the same interface. That
99 allows to implement any number of search criteria.
100 </P>
101 <P><I>Example:</I>
102 </P>
103 <PRE> button = ... .wrap(0);
104 frame.lookup(CoordinateLookup.leftOf(button)).
105 lookup(JTextField.class, new Any<JTextField>()).
106 ...;
107 </PRE><P>
108 Besides that, the interface defines methods to get the control, to
109 wrap it, to get the number of controls found, etc. .
110 </P>
111 <H3 CLASS="western">AbstractLookup</H3>
112 <P>This is an internal yet very important class. It implements
113 creating the sub-lookups. This particular implementation does it in a
114 way that the actual component hierarchy is not requested up until the
115 moment it has to be. It's only when there is a question on the actual
116 control list is asked, the hierarchy is explored.
117 </P>
118 <P><I>Example.</I> This does not query the AWT hierarchy:
119 </P>
120 <PRE> import org.jemmy.awt.FrameOperator;
121 ...
122 FrameOperator frame = ...
123 Lookup<JTextField> lookup = frame.lookup(JTextField.class, new TrueLookup<JTextField>());
124 </PRE><P>
125 These do:
126 </P>
127 <PRE> lookup.get(0);
128 lookup.wrap(0);
129 lookup.size();
130 lookup.wait(2);
131 </PRE><P>
132 <CODE>AbstractLookup</CODE> does not implement the functionality of
133 getting the control list, which is implemented by next two classes:
134 </P>
135 <H3 CLASS="western">HierarchyLookup and PlainLookup</H3>
136 <P>As it is clear from the names, these classes provide logic to deal
137 with hierarchical control structure and plain control list,
138 correspondentelly. Doing so, the implementation rely on two other
139 interfaces which specific to the component library: <CODE>ControlHierarchy</CODE>
140 and <CODE>ControlLookup</CODE>.
141 </P>
142 <H2 CLASS="western">Accessing/wrapping the controls</H2>
143 <P>Two methods <CODE>get(int)</CODE> and <CODE>wrap(int)</CODE> return
144 the control itself and the wrapper of it. The type of the returned
145 control is the <CODE>CONTROL</CODE> type parameter of <CODE>Lookup<CONTROL></CODE>
146 interface. Wrap type is <CODE>Wrap<CONTROL></CODE>, hence
147 there is no need to cast the results to get the control itself. There
148 is no need to cast the wrapper either, but this is described in a
149 separate document: <A HREF="interfaces.html">Jemmy control interfaces</A>
150 </P>
151 </BODY>
152 </HTML>
153