Upgrading from 2.3.1

Bryn Cooke edited this page Jul 21, 2013 · 13 revisions

Frames 2.4.0 is fully backward compatible with 2.3.1 so you won’t need to make any code changes if you upgrade.

However there have been some significant additions to the APIs to enable some new features and pave the way for more features in the future.

To this end you will find that some classes and method in Frames have been deprecated. However, these won’t be removed until at least the next major version of Tinkerpop.

For most frames users there will only be minor modifications to make to migrate to the new APIs, but for now this is completely optional.

Creating a FramedGraph

The recommended way of creating a FramedGraph is now via FramedGraphFactory rather than via the FramedGraph constructor.

FramedGraphFactory factory = new FramedGraphFactory();
FramedGraph framedGraph = factory.create(baseGraph);

This has a couple of benefits:

  • Resources can be shared between graphs.
  • Complex configuration of the FramedGraph can be pushed out to separate Module classes with their own APIs.

You should ideally use the same framed graph factory to create many framed graphs.
Note: That the gremlin groovy module is not included by default, this is to prevent having to start up a Groovy script engine if your application doesn’t require it. If you require @GremlinGroovy support make sure you are using the GremlinGroovyModule.

Extending FramedGraph functionality.

Modules are now used to encapsulate the extensions of FramedGraph. This brings together MethodHandlers(was AnnotationHandlers), TypeResolvers and FrameInitializers in to single units of configuration.

FramedGraphFactory may be constructed with any number of modules which will all be applied to every FramedGraph created.

FramedGraphFactory factory = new FramedGraphFactory(
    new GremlinGroovyModule(),
    new TypedGraphModuleBuilder().withClass(A.class).build());
FramedGraph framedGraph = factory.create(baseGraph);  //Groovy and typed graph created. 

The advantage of this is that each module may internally register any number of MethodHandler, TypeResolver and FrameInitializer leaving the you to concentrate on the high level feature you are adding to your FramedGraphs.

Use @InVertex or @OutVertex instead of @Domain and @Range

Framed edges have currently got additional internal state over and above the edge they are framing. This is the direction that the frame was created with. This direction is used to flip the meaning of @Domain and @Range.

In frames 2.4.0 two new annotations have been introduced that follow the Blueprints edge API more closely:

  • Edge.getVertex(Direction.Out) = @OutVertex
  • Edge.getVertex(Direction.In) = @InVertex

These statements will always be true regardless of the direction that the edge was created with.

Please note that @Domain and @Range do not map directly to either @InVertex or @OutVertex

@Domain and @Range have been deprecated.

Deprecation of FramedGraph.createEdge(edge, direction)

@InVertex and @OutVertex do not require the additional direction state on framed edges.
Therefore if you have migrated all your @Domain and @Range annotations to @InVertex and @OutVertex you can safely use FramedGraph.createEdge(edge) to create your edges without specifying the direction.

Use MethodHandler instead of AnnotationHandler

To support the new JavaHandler module and a future validation module AnnotationHandler has been deprecated in favour of MethodHandler.
The new MethodHandler interface is almost identical to AnnotationHandler with the exception of also receiving the frame object and not receiving the Direction parameter.