1 /*
2 * Copyright (c) 2018, Oracle and/or its affiliates. All rights reserved.
3 *
4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
5 *
6 * The contents of this file are subject to the terms of either the Universal Permissive License
7 * v 1.0 as shown at http://oss.oracle.com/licenses/upl
8 *
9 * or the following license:
10 *
11 * Redistribution and use in source and binary forms, with or without modification, are permitted
12 * provided that the following conditions are met:
13 *
14 * 1. Redistributions of source code must retain the above copyright notice, this list of conditions
15 * and the following disclaimer.
16 *
17 * 2. Redistributions in binary form must reproduce the above copyright notice, this list of
18 * conditions and the following disclaimer in the documentation and/or other materials provided with
19 * the distribution.
20 *
21 * 3. Neither the name of the copyright holder nor the names of its contributors may be used to
22 * endorse or promote products derived from this software without specific prior written permission.
23 *
24 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR
25 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
26 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
27 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
29 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
30 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
31 * WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
32 */
33 package org.openjdk.jmc.ui.charts;
34
35 import java.awt.Color;
36 import java.awt.geom.Point2D;
37 import java.awt.geom.Rectangle2D;
38
39 import org.openjdk.jmc.common.IDisplayable;
40
41 /**
42 * Visitor interface to gather information about values displayed in charts, typically in the
43 * vicinity of some coordinates. Suitable for tooltips, highlighting, hovering or snapping.
44 */
45 public interface IChartInfoVisitor {
46 public abstract class Adapter implements IChartInfoVisitor {
47
48 @Override
49 public boolean enterScope(String context, boolean fullyShown) {
50 return false;
51 }
52
53 @Override
54 public void leaveScope() {
55 }
56
57 @Override
58 public void hover(Object data) {
59 }
60
61 @Override
62 public void visit(IBucket bucket) {
63 }
64
65 @Override
66 public void visit(IPoint point) {
67 }
68
69 @Override
70 public void visit(ISpan span) {
71 }
72
73 @Override
74 public void visit(ITick tick) {
75 }
76
77 @Override
78 public void visit(ILane lane) {
79 }
80 }
81
82 public interface IBucket {
83 /**
84 * Get a bucket equivalent to this bucket, but guaranteed to be unchanged at least until the
85 * chart changes state.
86 *
87 * @return
88 */
89 IBucket keeper();
90
91 String getName();
92
93 Color getColor();
94
95 Rectangle2D getTarget();
96
97 IDisplayable getRange();
98
99 IDisplayable getStartX();
100
101 IDisplayable getEndX();
102
103 IDisplayable getWidth();
104
105 IDisplayable getY();
106
107 Object getPayload();
108 }
109
110 public interface IPoint {
111 /**
112 * Get a point equivalent to this point, but guaranteed to be unchanged at least until the
113 * chart changes state.
114 *
115 * @return
116 */
117 IPoint keeper();
118
119 String getName();
120
121 Color getColor();
122
123 Point2D getTarget();
124
125 IDisplayable getX();
126
127 IDisplayable getY();
128 }
129
130 public interface ISpan {
131 /**
132 * Get a span equivalent to this span, but guaranteed to be unchanged at least until the
133 * chart changes state.
134 *
135 * @return
136 */
137 ISpan keeper();
138
139 Color getColor();
140
141 Rectangle2D getTarget();
142
143 IDisplayable getRange();
144
145 IDisplayable getStartX();
146
147 IDisplayable getEndX();
148
149 IDisplayable getWidth();
150
151 Object getPayload();
152
153 String getDescription();
154 }
155
156 public interface ITick {
157 Point2D getTarget();
158
159 IDisplayable getValue();
160 }
161
162 public interface ILane {
163 String getLaneName();
164
165 String getLaneDescription();
166 }
167
168 /**
169 * Enter a context scope described by {@code context}. Scopes may be nested.
170 *
171 * @param context
172 * @param fullyShown
173 * true if the entire {@code context} string is fully visible in the GUI
174 * @return true to receive a {@link #leaveScope()} when this context goes out of scope.
175 */
176 boolean enterScope(String context, boolean fullyShown);
177
178 void leaveScope();
179
180 /**
181 * Deliver supplementary information about the hovered rendered item to the Visitor.
182 * <p>
183 * To be used in conjunction with an rendered item's {@code infoAt()} to
184 * deliver supplementary information about the currently hovered object to the Visitor.
185 *
186 * @param data
187 */
188 void hover(Object data);
189
190 /**
191 * Visit a bucket in a histogram.
192 * <p>
193 * Note that the provided {@link IBucket} instance may be reused and thus cannot be directly
194 * saved by the visitor. Visitors wishing to delay processing of {@link IBucket}s, can do so by
195 * requesting an instance that will remain valid at least until the chart changes state, through
196 * the {@link IBucket#keeper()} method.
197 *
198 * @param bucket
199 */
200 void visit(IBucket bucket);
201
202 /**
203 * Visit a data point in a line chart or similar.
204 * <p>
205 * Note that the provided {@link IPoint} instance may be reused and thus cannot be directly
206 * saved by the visitor. Visitors wishing to delay processing of {@link IPoint}s, can do so by
207 * requesting an instance that will remain valid at least until the chart changes state, through
208 * the {@link IPoint#keeper()} method.
209 *
210 * @param point
211 */
212 void visit(IPoint point);
213
214 /**
215 * Visit a span in a Gantt chart or similar.
216 * <p>
217 * Note that the provided {@link ISpan} instance may be reused and thus cannot be directly saved
218 * by the visitor. Visitors wishing to delay processing of {@link ISpan}s, can do so by
219 * requesting an instance that will remain valid at least until the chart changes state, through
220 * the {@link ISpan#keeper()} method.
221 *
222 * @param span
223 */
224 void visit(ISpan span);
225
226 /**
227 * Visit a tick mark (or a bucket boundary/sub tick mark) on a chart axis.
228 * <p>
229 * The provided {@link ITick} instance may be directly saved by the visitor and will remain
230 * valid at least until the chart changes state.
231 *
232 * @param tick
233 */
234 void visit(ITick tick);
235
236 /**
237 * Visits the header part of a line chart, normally a caption in the form of a label.
238 *
239 * @param lane
240 */
241 void visit(ILane lane);
242 }