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 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 visit(IBucket bucket) {
59 }
60
61 @Override
62 public void visit(IPoint point) {
63 }
64
65 @Override
66 public void visit(ISpan span) {
67 }
68
69 @Override
70 public void visit(ITick tick) {
71 }
72
73 @Override
74 public void visit(ILane lane) {
75 }
76 }
77
78 public interface IBucket {
79 /**
80 * Get a bucket equivalent to this bucket, but guaranteed to be unchanged at least until the
81 * chart changes state.
82 *
83 * @return
84 */
85 IBucket keeper();
86
87 String getName();
88
89 Color getColor();
90
91 Rectangle2D getTarget();
92
93 IDisplayable getRange();
94
95 IDisplayable getStartX();
96
97 IDisplayable getEndX();
98
99 IDisplayable getWidth();
100
101 IDisplayable getY();
102
103 Object getPayload();
104 }
105
106 public interface IPoint {
107 /**
108 * Get a point equivalent to this point, but guaranteed to be unchanged at least until the
109 * chart changes state.
110 *
111 * @return
112 */
113 IPoint keeper();
114
115 String getName();
116
117 Color getColor();
118
119 Point2D getTarget();
120
121 IDisplayable getX();
122
123 IDisplayable getY();
124 }
125
126 public interface ISpan {
127 /**
128 * Get a span equivalent to this span, but guaranteed to be unchanged at least until the
129 * chart changes state.
130 *
131 * @return
132 */
133 ISpan keeper();
134
135 Color getColor();
136
137 Rectangle2D getTarget();
138
139 IDisplayable getRange();
140
141 IDisplayable getStartX();
142
143 IDisplayable getEndX();
144
145 IDisplayable getWidth();
146
147 Object getPayload();
148
149 String getDescription();
150 }
151
152 public interface ITick {
153 Point2D getTarget();
154
155 IDisplayable getValue();
156 }
157
158 public interface ILane {
159 String getLaneName();
160
161 String getLaneDescription();
162 }
163
164 /**
165 * Enter a context scope described by {@code context}. Scopes may be nested.
166 *
167 * @param context
168 * @param fullyShown
169 * true if the entire {@code context} string is fully visible in the GUI
170 * @return true to receive a {@link #leaveScope()} when this context goes out of scope.
171 */
172 boolean enterScope(String context, boolean fullyShown);
173
174 void leaveScope();
175
176 /**
177 * Visit a bucket in a histogram.
178 * <p>
179 * Note that the provided {@link IBucket} instance may be reused and thus cannot be directly
180 * saved by the visitor. Visitors wishing to delay processing of {@link IBucket}s, can do so by
181 * requesting an instance that will remain valid at least until the chart changes state, through
182 * the {@link IBucket#keeper()} method.
183 *
184 * @param bucket
185 */
186 void visit(IBucket bucket);
187
188 /**
189 * Visit a data point in a line chart or similar.
190 * <p>
191 * Note that the provided {@link IPoint} instance may be reused and thus cannot be directly
192 * saved by the visitor. Visitors wishing to delay processing of {@link IPoint}s, can do so by
193 * requesting an instance that will remain valid at least until the chart changes state, through
194 * the {@link IPoint#keeper()} method.
195 *
196 * @param point
197 */
198 void visit(IPoint point);
199
200 /**
201 * Visit a span in a Gantt chart or similar.
202 * <p>
203 * Note that the provided {@link ISpan} instance may be reused and thus cannot be directly saved
204 * by the visitor. Visitors wishing to delay processing of {@link ISpan}s, can do so by
205 * requesting an instance that will remain valid at least until the chart changes state, through
206 * the {@link ISpan#keeper()} method.
207 *
208 * @param span
209 */
210 void visit(ISpan span);
211
212 /**
213 * Visit a tick mark (or a bucket boundary/sub tick mark) on a chart axis.
214 * <p>
215 * The provided {@link ITick} instance may be directly saved by the visitor and will remain
216 * valid at least until the chart changes state.
217 *
218 * @param tick
219 */
220 void visit(ITick tick);
221
222 /**
223 * Visits the header part of a line chart, normally a caption in the form of a label.
224 *
225 * @param lane
226 */
227 void visit(ILane lane);
228 }