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.

h3. Creating a FramedGraph

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

```java
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@.*

h3. 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.

```java
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.

h3. 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.

h3. 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.

h3. 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.




 





