# Java API Help

#### Page Contents

- Basic Principles.
- Important Concepts and Terms.
- Installation.
- Graph API.
- Bounds Language.
- Bounds API.
- Job Broker API.

#### Basic Principles

When you work with ** GraphBase**, you work with

**graphs**. GraphBase stores data as one large (usually connected)

**graph**. Data is delivered to GraphBase as small

**graphs**, a query to GraphBase returns data as a

**graph**and the smallest transactional unit is a

**graph**. GraphBase also contains visual tools that let you think about, manipulate, and store your data - as

**graphs**.

#### Important Concepts and Terms

- a graph structured in Graph Simple Form.*Graph*- a vertex (or node) within a Graph.*Vertex*- an arc (or edge) connecting vertices within a Graph.*Arc*- a Vertex Set. A package which encapsulates a Vertex and its incident Arcs.*VSet*- a single Graph maintained by one or more*Super-Graph*Nodes.*GraphBase*- the aggregated content of all GraphBase Super-Graphs.*Concept Space*- a 128-bit identifier used primarily to identify a vertex within Concept Space.*GlobalID*- a to-be-replaced GlobalID used when attaching new vertices to a graph.*Surrogate GlobalID*- a GraphBase server application which stores sub-graphs and processes Jobs.*Node*- a Node with limited functionality that relies on a full Node for storage and processing.*Proxy Node*- a query object used to extract a sub-graph from a graph, or from a*Bounds*Node.*GraphBase*- text that can be parsed to create a Bounds object.*Bounds Language*- the GraphBase unit of work. Used for query, delivery and operations upon one or more Graphs.*Job*- an Interface which accepts a Job and returns its result.*Job Broker*- a Graph, submitted with a Job, that allows access to parts of a Super-Graph.*Credentials*- a snippet of Java that allows manipulation of graphs within a Job.*Handler*- a snippet of Java that may be embedded within a Super-Graph Vertex.*Agent*- a class used for configuring package-specific parameters and injecting dependencies*Package Runner*

#### Installation

- Make sure you have the Java SE6 or newer runtime (JRE) installed.
- Download the latest GraphBaseAgility.zip file and unpack it.
- Add
*GraphBaseProxy.jar*and the*lib*library to your application's ClassPath.

#### Graph API

The Graph class sample methods below are cut from the JavaDoc that comes with GraphBase Agility.

The class comes with a wealth of functionality to let you create, manipulate, analyse and compare Graphs.

- Create a new Graph using
.*newSingleVertexGraph()* - Add to it using
.*newAddedVertexGraph()* - Compare it with another Graph using
.*and()* - Merge it with another Graph using
.*or()* - Query it using
.*subGraph()* - Extract some useful features using
.*getLeafIDs()* - Convert it directly to useful Java Objects using
.*asObjectsList()* - Save it for later use or for viewing in
*GraphPad*using.*saveAsXMLFile()*

Download GraphSampleMethodsJava.txt to see these methods applied in a simple program.

#### Bounds Language

A Bounds object is query that, when applied to a local Graph, or to a Super-Graph, returns a sub-graph. A Bounds query describes a set of simultaneous graph traversals together with the operations applied to, and between, those traversals. Each Bounds object contains...

- A filter
- to be applied to a vertex's incident arc.*expression* - An optional
object - vertices that the filter expression will operate on.*fromBounds* - An integer
- the number of consecutive traversals that will use the expression.*reach* - Optional
- to select a subset of the vertices normally returned.*range cursors* - An optional
object - that will receive vertices returned by this Bounds.*toBounds* - Optional
objects - upon which extended boolean operations may be performed. These may also receive vertices returned by this Bounds.*encapsulatedBounds*

The filter epression is composed of one or more simple filters - called ** ExpressionFragment**s - that are applied to either the arc

**or the arc**

*type***. The easiest way to work with these is to use**

*hint***.**

*Bounds Language*Let's start by introducing the features, or tokens, used by the language. First up, some basic structural tokens that encapsulate and control evaluation order.

Structural Tokens | ||

Token | Name | Description |

{ | BOUNDS_OPEN | Opening Bounds encapsulation token. |

} | BOUNDS_CLOSE | Closing Bounds encapsulation token. |

( | OPEN_BRACKET | Encapsulates a filter expression and overrides evaluation order. |

) | CLOSE_BRACKET | Encapsulates a filter expression and overrides evaluation order. |

from | BOUNDS_FROM | Results will be taken FROM the following Bounds encapsulation. |

pass | BOUNDS_PASS | PASS results of the following filter expression on. |

to | BOUNDS_TO | Pass resulting vertices TO the following encapsulation. |

Tokens in this next block are used to filter on the ** type** of a vertex's incident arcs.

Arc Type Filter Operations | ||

Token | Name | Description |

all | ALL_ARCS | All of this vertex's incident arcs. |

[ | ALL_CONTAINED_BY_THIS | Arcs with a type that implies far vertices are contained by this one. For GSF this means types HAS_A, MUTUAL_HAS and SAME_AS. |

] | ALL_CONTAINING_THIS | Arcs with a type that implies that far vertices contain this one. For GSF this means types IS_OF, MUTUAL_HAS and SAME_AS. |

![ | ALL_NOT_CONTAINED_BY_THIS | Arcs with a type that implies far vertices are not contained by this one. For GSF this means types IS_OF and SAME_AS. |

!] | ALL_NOT_CONTAINING_THIS | Arcs with a type that implies that far vertices do no contain this one. For GSF this means types HAS_A and SAME_AS. |

T= | TYPE_IS | Operand is an integer. Filter returns arcs of the operand's type. |

T!= | TYPE_IS_NOT | Operand is an integer. Filter returns arcs NOT of the operand's type. |

Some examples...

**{ from {@1~51397} pass All}**- a graph of**all**vertices adjacent to a vertex of known ID.**{ from {@1~51397} pass [ }**- vertices*contained*by this vertex.

Each arc may carry an heuristic or ** hint** as to the contents of its pointed-to vertex. This feature allows arcs to behave as an

*adjacent index*and it dramatically-improves query speed for graphs with known structure. Tokens for filtering using hints are these.

Arc Hint Filter Operations | ||

Token | Name | Description |

H= | EQUAL_TO | Incident arcs where hint equals operand. |

H!= | NOT_EQUAL_TO | Incident arcs where hint does not equal operand. |

H> | GREATER_THAN | Arcs where hint is greater than operand. * |

H>= | NOT_LESS_THAN | Arcs where hint is greater than or equal to operand. * |

H< | LESS_THAN | Arcs where hint is less than operand. * |

H<= | NOT_GREATER_THAN | Arcs where hint is less than or equal to operand. * |

* String hints are evaluated in UTF-8 order. |

Some examples...

**{ from {@1~1} pass H='name' to { pass H='Fred' }}**- framework and arc hints as an index.**{ from {@1~1} pass H='age' to { pass H>18 }}**- framework and arc hints as a range query.

Filter operations can be further refined by applying boolean operations to two or more expressions.

Expression Association Operations - In Operation Precedence Order | ||

Token | Name | Description |

and | AND | Returns arcs that are common to both expressions. |

or | OR | Returns arcs that are found in the results of either expression. |

xor | XOR | Returns arcs that are found in the results of either expression but not in both. |

andnot | AND_NOT | Returns arcs that are found in the results of the first expression, but not in the second |

Use ( encapsulating brackets ) to ensure that evaluation order is as expected. |

Extending the above examples...

**{ from {@1~1} pass H='name' to { pass H>'Fred' and H<'Free' }}**- get Freddy, Frederick and other derivations.**{ from {@1~1} pass H='age' to { pass H>=18 and H<40 }}**- over 18, but under 40.

Expression Modifiers | ||

Token | Name | Description |

* | REACH | Applies the expression to the specified number of traversals. e.g *3 Default is 1. |

# | RESULT_RANGE | Returns the range of expression results specified by the modifier indices. e.g. #1-100 |

Extending an earlier example above to perform three traversals using the same expression...

**{ pass {@1~51397} to [ *3 }**- applies the containment expression to successive results.

Similar operations can also be applied between evaluated Bounds objects. The result of a Bounds Association Operation is a complete Graph.

Bounds Association Operations - In Operation Precedence Order | ||

Token | Name | Description |

AND | AND | Returns a graph of vertices that are common to the results of both Bounds objects. |

XAND | XAND | As for AND, but eXtended to include the vertices used to traverse to the found common vertices. |

OR | OR | Returns a graph of vertices that are found in the results of either Bounds objects. |

XOR | XOR | Returns a graph of vertices that are found in the results of either Bounds objects but not in both. |

ANDNOT | AND_NOT | Returns a graph of vertices that are found in the results of the first Bounds object, but not in the second. |

**@1~51397** is the Semantic Framework conceptID for "actor".

See http://graphbase.net/semantic/@1~51397. This Bounds query returns a graph of Actors, 18 to 40 years of age. Use of the XAND operator ensures that the returned graph can be further explored using the same frameworks.

#### Bounds API

Bounds Language is the easiest way to create a new or simple Bounds query, but the **Bounds API** can be useful for complex queries or for the creation of Bounds queries that conform to regularly-used patterns.

lets you collect in bulk by applying a simple template.*newCompoundBounds()*for a graph of what multiple vertices have in common.*newMultipleVertexIDAttachedBounds()*get the intersection of many traversal paths.*newMultipleVertexIDContainmentBounds()*makes it easy to program using a single template pattern.*vertexIDReplaced()*

#### Job Broker API

Once you've connected to a GraphBase Node, you can query a super-graph, add to it or manipulate it via a Job Broker.

- Use
for most jobs issued against a single Node.*issueAndWaitForJob()* - Use
if your application can come back for its results.*issueJob()* - Use
to check on the progress of long-running or distributed jobs.*hasCompleted()* - Use
for automated super-graph manipulations.*issueAndForgetJob()*

Please feel free to use the Comments section below if there's anything you'd like to see addressed in this Help document.