1 /*
2 * Copyright (c) 2010, 2013, 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. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package com.oracle.javafx.jmx;
27
28 /**
29 * The <code>SGMXBean</code> represents a standard JMX interface to the JavaFX application.
30 * The interface is supposed to be used by tools (debugger) and provides functionality
31 * to obtain Scene-graph related information and information about nodes.
32 */
33 public interface SGMXBean {
34
35 /**
36 * Pauses the Scene-graph which means it pause all animations, media players, etc.
37 * To resume the Scene-graph to normal operation call {@link #resume}.
38 *
39 * If the Scene-graph is already "PAUSED" then this method has no effect.
40 */
41 void pause();
42
43 /**
44 * Resumes the previously paused Scene-graph into the normal operation.
45 *
46 * If the Scene-graph is running normally (not "PAUSED") then this method has no effect.
47 */
48 void resume();
49
50 /**
51 * Produces single JavaFX pulse and pauses the Scene-graph again. It is
52 * similar to STEP feature in debuggers.
53 *
54 * The Scene-graph should be already "PAUSED" (by calling {@link #pause()} method)
55 * prior to calling this function otherwise the {@link IllegalStateException} is thrown.
56 *
57 * @throws IllegalStateException when Scene-graph is not "PAUSED"
58 */
59 void step() throws IllegalStateException;
60
61 /**
62 * Returns the list of JavaFX windows. Each window is identified by unique
63 * number identifier. The identifier is used as an input to
64 * {@link #getSGTree(int)} method.
65 *
66 * The {@link #pause()} method should be called prior to calling this method.
67 * Otherwise the {@link IllegalStateException} is thrown.
68 *
69 * The result is in the format of JSON string.
70 *
71 * @return the list of all JavaFX windows in JSON format
72 * @throws IllegalStateException when Scene-graph is not "PAUSED"
73 */
74 String getWindows() throws IllegalStateException;
75
76 /**
77 * Returns the Scene-graph hierarchy in a simple tree-like model for
78 * given window. Every node is identified by unique number identifier.
79 * The identifier is used to query node's properties with methods like
80 * {@link #getCSSInfo(int)}.
81 *
82 * The {@link #pause()} method should be called prior to calling this method.
83 * Otherwise the {@link IllegalStateException} is thrown.
84 *
85 * The result is in the format of JSON string.
86 *
87 * @param windowId unique window identifier obtained by {@link #getWindows()}
88 * @return the simple tree-like model of the Scene-graph in JSON format
89 * @throws IllegalStateException when Scene-graph is not "PAUSED"
90 */
91 String getSGTree(int windowId) throws IllegalStateException;
92
93 /**
94 * Retrieves the CSS information about the particular node.
95 *
96 * The {@link #pause()} method should be called prior to calling this method.
97 * Otherwise the {@link IllegalStateException} is thrown.
98 *
99 * @param nodeId node identifier obtained by {@link #getSGTree(int)}
100 * @return list of key-value pairs holding CSS information, result is in JSON format
101 * @throws IllegalStateException when Scene-graph is not "PAUSED"
102 */
103 String getCSSInfo(int nodeId) throws IllegalStateException;
104
105 /**
106 * Retrieves the bounds information about the particular node. Bounds are in scene's
107 * coordinate system.
108 *
109 * @param nodeId node identifier obtained by {@link #getSGTree(int)}
110 * @return bounds information (x, y, width and height) for given node in scene's coordinate system,
111 * result is in JSON format
112 * @throws IllegalStateException when Scene-graph is not "PAUSED"
113 */
114 String getBounds(int nodeId) throws IllegalStateException;
115
116 /**
117 * Adds the node with the nodeId to the list of nodes that are to be
118 * highlighted in the scene. The nodeId is to be retrieved using
119 * the {@link #getSGTree(int)} method.
120 *
121 * @param nodeId the id of the node to be highlighted
122 * @throws IllegalStateException when Scene-graph is not "PAUSED"
123 */
124 void addHighlightedNode(int nodeId) throws IllegalStateException;
125
126 /**
127 * Removes the nodeId node from the list of nodes that are to be
128 * highlighted in the scene. The nodeId is to be retrieved using
129 * the {@link #getSGTree(int)} method.
130 *
131 * @param nodeId the id of the node to be removed
132 * @throws IllegalStateException when Scene-graph is not "PAUSED"
133 */
134 void removeHighlightedNode(int nodeId) throws IllegalStateException;
135
136 /**
137 * Adds the specified region to the list of regions to be highlighted
138 * in the scene. The windowId is to be retrieved using the
139 * {@link #getWindows()} method.
140 *
141 * @param windowId unique window identifier obtained by {@link #getWindows()}
142 * @param x x coordinate of the region
143 * @param y y coordinate of the region
144 * @param w width of the region
145 * @param h height of the region
146 * @throws IllegalStateException when Scene-graph is not "PAUSED"
147 */
148 void addHighlightedRegion(int windowId, double x, double y, double w, double h)
149 throws IllegalStateException;
150
151 /**
152 * Removes the specified region from the list of regions to be highlighted
153 * in the scene. The windowId is to be retrieved using the
154 * {@link #getWindows()} method.
155 *
156 * @param windowId unique window identifier obtained by {@link #getWindows()}
157 * @param x x coordinate of the region
158 * @param y y coordinate of the region
159 * @param w width of the region
160 * @param h height of the region
161 * @throws IllegalStateException when Scene-graph is not "PAUSED"
162 */
163 void removeHighlightedRegion(int windowId, double x, double y, double w, double h)
164 throws IllegalStateException;
165
166 /**
167 * Makes a screen-shot of the selected node in the scene's coordinates
168 * and stores it into a temporary file in the PNG format.
169 * Absolute path to this file is returned.
170 *
171 * The {@link #pause()} method should be called prior to calling this method.
172 * Otherwise the {@link IllegalStateException} is thrown.
173 *
174 * @param nodeId node identifier obtained by {@link #getSGTree(int)}
175 * @return the absolute path to the PNG file with the image
176 * @throws IllegalStateException when Scene-graph is not "PAUSED"
177 */
178 String makeScreenShot(int nodeId) throws IllegalStateException;
179
180 /**
181 * Makes a screen-shot of the specified region in the scene's coordinates
182 * and stores it into a temporary file in the PNG format.
183 * Absolute path to this file is returned.
184 *
185 * The {@link #pause()} method should be called prior to calling this method.
186 * Otherwise the {@link IllegalStateException} is thrown.
187 *
188 * @param windowId unique window identifier obtained by {@link #getWindows()}
189 * @param x x coordinate of the region
190 * @param y y coordinate of the region
191 * @param w width of the region
192 * @param h height of the region
193 * @return the absolute path to the PNG file with the image
194 * @throws IllegalStateException when Scene-graph is not "PAUSED"
195 */
196 String makeScreenShot(int windowId, double x, double y, double w, double h)
197 throws IllegalStateException;
198
199 }