1 2 /* 3 * Copyright (c) 2017, 2018, Oracle and/or its affiliates. All rights reserved. 4 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 5 * 6 * This code is free software; you can redistribute it and/or modify it 7 * under the terms of the GNU General Public License version 2 only, as 8 * published by the Free Software Foundation. 9 * 10 * This code is distributed in the hope that it will be useful, but WITHOUT 11 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 12 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 13 * version 2 for more details (a copy is included in the LICENSE file that 14 * accompanied this code). 15 * 16 * You should have received a copy of the GNU General Public License version 17 * 2 along with this work; if not, write to the Free Software Foundation, 18 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 19 * 20 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 21 * or visit www.oracle.com if you need additional information or have any 22 * questions. 23 */ 24 25 /** 26 * Send your graphs to <b>IGV</b> via a socket or a file. This package allows one to easily encode 27 * any graph-like data structure and send it for visualization to <em>OracleLab's Ideal Graph 28 * Visualizer</em> tool. Assuming you already have your own data structure that contains 29 * <b>nodes</b> and <b>edges</b> among them, creating a {@link org.graalvm.graphio.GraphOutput} 30 * specialized for your data is a matter of implementing a single interface: 31 * 32 * {@link org.graalvm.graphio.GraphJavadocSnippets#acmeGraphStructure} 33 * 34 * The {@link org.graalvm.graphio.GraphStructure} interface defines the set of operations that are 35 * needed by the <em>graph protocol</em> to encode a graph into the <b>IGV</b> expected format. The 36 * graph structure is implemented as a so called 37 * <a href="http://wiki.apidesign.org/wiki/Singletonizer">singletonizer</a> API pattern: there is no 38 * need to change your data structures or implement some special interfaces - everything needed is 39 * provided by implementing the {@link org.graalvm.graphio.GraphStructure} operations. 40 * <p> 41 * The next step is to turn this graph structure into an instance of 42 * {@link org.graalvm.graphio.GraphOutput}. To do so use the associated 43 * {@link org.graalvm.graphio.GraphOutput.Builder builder} just like shown in the following method: 44 * 45 * {@link org.graalvm.graphio.GraphJavadocSnippets#buildOutput} 46 * 47 * Now you are ready to dump your graph into <b>IGV</b>. Where to obtain the right channel? One 48 * option is to create a {@link java.nio.channels.FileChannel} and dump the data into a file 49 * (preferrably with <code>.bgv</code> extension). The other is to open a socket to port 50 * <code>4445</code> (the default port <b>IGV</b> listens to) and dump the data there. Here is an 51 * example: 52 * 53 * {@link org.graalvm.graphio.GraphJavadocSnippets#dump} 54 * 55 * Call the {@code dump} method with pointer to file {@code diamond.bgv} and then you can open the 56 * file in <b>IGV</b>. The result will look like this: 57 * <p> 58 * <img src="doc-files/diamond.png"> 59 * <p> 60 * You can verify the behavior directly in the <b>IGV</b> by downloading 61 * <a href="doc-files/diamond.bgv">diamond.bgv</a> file generated from the above diamond structure 62 * graph. 63 * <p> 64 * The primary <b>IGV</b> focus is on graphs used by the compiler. As such they aren't plain graphs, 65 * but contain various compiler oriented attributes: 66 * <ul> 67 * <li>{@linkplain org.graalvm.graphio.GraphBlocks code blocks} information</li> 68 * <li>{@linkplain org.graalvm.graphio.GraphElements method and fields} information</li> 69 * <li>Advanced support for {@linkplain org.graalvm.graphio.GraphTypes recognizing types}</li> 70 * </ul> 71 * all these additional interfaces ({@link org.graalvm.graphio.GraphBlocks}, 72 * {@link org.graalvm.graphio.GraphElements} and {@link org.graalvm.graphio.GraphTypes}) are 73 * optional - they don't have to be provided. As such they can be specified via 74 * {@link org.graalvm.graphio.GraphOutput.Builder} instance methods, which may, but need not be 75 * called at all. Here is an example: 76 * 77 * {@link org.graalvm.graphio.GraphJavadocSnippets#buildAll} 78 * 79 * All these interfaces follow the 80 * <a href="http://wiki.apidesign.org/wiki/Singletonizer">singletonizer</a> API pattern again - e.g. 81 * no need to change your existing data structures, just implement the operations provided by the 82 * interfaces you pass into the builder. By combining these interfaces together you can get as rich, 83 * colorful, source linked graphs as the compiler produces to describe its optimizations. 84 */ 85 86 87 package org.graalvm.graphio;