Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ under the License.

In the previous section we discussed the implications of association proxies for single-ended associations. However, the same applies with many-ended associations.

In the case of collection types, these implement the link:../api/grails/gorm/rx/collection/RxPersistentCollection.html[RxPersistentCollection] and again can be subscribed to:
In the case of collection types, these implement the link:../../api/grails/gorm/rx/collection/RxPersistentCollection.html[RxPersistentCollection] and again can be subscribed to:


[source,groovy]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ for (Book book in books) {
}
----

In the above example RxGORM has no choice but to block in order to load the association lazy and access the `name`! Typically, you do not want your reactive application to block at any point, so in order to get around this, each proxy loaded by GORM implements the link:../api/grails/gorm/rx/proxy/ObservableProxy.html[ObservableProxy] interface. That means the above code can be written in a non-blocking manner:
In the above example RxGORM has no choice but to block in order to load the association lazy and access the `name`! Typically, you do not want your reactive application to block at any point, so in order to get around this, each proxy loaded by GORM implements the link:../../api/grails/gorm/rx/proxy/ObservableProxy.html[ObservableProxy] interface. That means the above code can be written in a non-blocking manner:

[source,groovy]
----
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ When using RxGORM each entity that you persist to the database is known as a dom

If you are using RxGORM within Grails you can create a domain class with the `create-domain-class` command provided by the command line. Alternatively if you are not using Grails simply creating a Groovy class within `src/main/groovy` of your project will suffice.

A domain class must as a minimum implement the link:../api/grails/gorm/rx/RxEntity.html[RxEntity] trait.
A domain class must as a minimum implement the link:../../api/grails/gorm/rx/RxEntity.html[RxEntity] trait.

However, when using RxGORM for MongoDB you should instead implement the `grails.gorm.rx.mongodb.RxMongoEntity` trait. For example:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ new RxMongoDatastoreClient(

<1> The `MongoClient` instance
<2> The name of the default database to save objects to
<3> One or many classes that implement link:../api/grails/gorm/rx/RxEntity.html[RxEntity]
<3> One or many classes that implement link:../../api/grails/gorm/rx/RxEntity.html[RxEntity]

The `org.grails.datastore.rx.mongodb.RxMongoDatastoreClient` class is required to initialize RxGORM for MongoDB.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ def query = Book.where {
}
----

Note that no query is actually executed directly, instead the `where(Closure)` method returns an instance of link:../api/grails/gorm/rx/DetachedCriteria.html[DetachedCriteria].
Note that no query is actually executed directly, instead the `where(Closure)` method returns an instance of link:../../api/grails/gorm/rx/DetachedCriteria.html[DetachedCriteria].

Like an `rx.Observable`, the `DetachedCriteria` class can be subscribed to:

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ The schema has several properties that can be modified.

=== List Arguments

A map where the key is a string (one of link:{api}/org/grails/gorm/graphql/fetcher/impl/EntityDataFetcher.html#ARGUMENTS[EntityDataFetcher.ARGUMENTS]) and the value is the class the argument should be coerced into.
A map where the key is a string (one of link:../../../api/org/grails/gorm/graphql/fetcher/impl/EntityDataFetcher.html#ARGUMENTS[EntityDataFetcher.ARGUMENTS]) and the value is the class the argument should be coerced into.

[source,groovy]
----
Expand Down Expand Up @@ -71,7 +71,7 @@ The following options are available to configure for Grails applications using t
|If the setting is not provided, the `grails.databinding.dateParsingLenient` will be used.
|`grails.gorm.graphql.listArguments`
|Map<String, Class>
|The default arguments in link:{api}/org/grails/gorm/graphql/fetcher/impl/EntityDataFetcher.html#ARGUMENTS[EntityDataFetcher.ARGUMENTS]
|The default arguments in link:../../../api/org/grails/gorm/graphql/fetcher/impl/EntityDataFetcher.html#ARGUMENTS[EntityDataFetcher.ARGUMENTS]
|
|`grails.gorm.graphql.browser`
| Boolean
Expand All @@ -83,11 +83,11 @@ The following options are available to configure for Grails applications using t

Data fetchers in GraphQL have a "context". The context is really just an Object field that can contain anything you like with the purpose of exposing it to the data fetching environment. For example, the default context created by the plugin is a Map that contains the request locale. The locale is used to render validation error messages.

TIP: If you prefer to set the context to a custom class, implement link:{api}/org/grails/gorm/graphql/fetcher/context/LocaleAwareContext.html[LocaleAwareContext] and the default validation errors response handler will retrieve the locale from the object.
TIP: If you prefer to set the context to a custom class, implement link:../../../api/org/grails/gorm/graphql/fetcher/context/LocaleAwareContext.html[LocaleAwareContext] and the default validation errors response handler will retrieve the locale from the object.

It is common to need to manipulate the context to include data that some or all of your data fetchers might need. If a fetcher needs to be aware of the current user and you are using the spring security plugin, you may want to add the `springSecurityService` to the context.

To customize the context, register a bean named "graphQLContextBuilder" of type link:{api}/org/grails/gorm/graphql/plugin/GraphQLContextBuilder.html[GraphQLContextBuilder]. If the default errors handler is being used, extend from link:{api}/org/grails/gorm/graphql/plugin/DefaultGraphQLContextBuilder.html[DefaultGraphQLContextBuilder] and add to the result of the super method call.
To customize the context, register a bean named "graphQLContextBuilder" of type link:../../../api/org/grails/gorm/graphql/plugin/GraphQLContextBuilder.html[GraphQLContextBuilder]. If the default errors handler is being used, extend from link:../../../api/org/grails/gorm/graphql/plugin/DefaultGraphQLContextBuilder.html[DefaultGraphQLContextBuilder] and add to the result of the super method call.

[source,groovy]
.src/main/groovy/demo/MyGraphQLContextBuilder.groovy
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ under the License.

== Custom Naming Conventions

The names used to describe entities is configurable through the use of an link:{api}/org/grails/gorm/graphql/entity/GraphQLEntityNamingConvention.html[GraphQLEntityNamingConvention].
The names used to describe entities is configurable through the use of an link:../../../api/org/grails/gorm/graphql/entity/GraphQLEntityNamingConvention.html[GraphQLEntityNamingConvention].

The class controls the name of the default operations and the names of the GraphQL types built from the GORM entities.

Expand All @@ -37,7 +37,7 @@ schema.namingConvention = new MyNamingConvention()

=== Grails

To override the naming convention in a Grails application, register a bean with the name "graphQLEntityNamingConvention" that extends link:{api}/org/grails/gorm/graphql/entity/GraphQLEntityNamingConvention.html[GraphQLEntityNamingConvention].
To override the naming convention in a Grails application, register a bean with the name "graphQLEntityNamingConvention" that extends link:../../../api/org/grails/gorm/graphql/entity/GraphQLEntityNamingConvention.html[GraphQLEntityNamingConvention].

[source,groovy]
.resources.groovy
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ By configuring the list operation to paginate, instead of a list of results bein

==== Customization

It is possible to customize how the pagination response is created through the creation of a link:{api}/org/grails/gorm/graphql/response/pagination/GraphQLPaginationResponseHandler.html[GraphQLPaginationResponseHandler].
It is possible to customize how the pagination response is created through the creation of a link:../../../api/org/grails/gorm/graphql/response/pagination/GraphQLPaginationResponseHandler.html[GraphQLPaginationResponseHandler].

How you can supply your own pagination response handler depends on whether the library is being used standalone or part of a Grails application.

Expand All @@ -123,7 +123,7 @@ beans = {
}
----

NOTE: Data fetchers must respond according to the object type definition created by the pagination response handler. When supplying your own data fetcher, implement link:{api}/org/grails/gorm/graphql/fetcher/PaginatingGormDataFetcher.html[PaginatingGormDataFetcher] and the response handler will be populated for you. The response handler is responsible for creating the response in order to assure it is compatible.
NOTE: Data fetchers must respond according to the object type definition created by the pagination response handler. When supplying your own data fetcher, implement link:../../../api/org/grails/gorm/graphql/fetcher/PaginatingGormDataFetcher.html[PaginatingGormDataFetcher] and the response handler will be populated for you. The response handler is responsible for creating the response in order to assure it is compatible.

== Custom Operations

Expand Down Expand Up @@ -231,24 +231,24 @@ The above example will function properly, however it is missing out on one of th
|===
|Type|Class
|GET
|link:{api}/org/grails/gorm/graphql/fetcher/impl/SingleEntityDataFetcher.html[SingleEntityDataFetcher]
|link:../../../api/org/grails/gorm/graphql/fetcher/impl/SingleEntityDataFetcher.html[SingleEntityDataFetcher]
|LIST
|link:{api}/org/grails/gorm/graphql/fetcher/impl/EntityDataFetcher.html[EntityDataFetcher]
|link:../../../api/org/grails/gorm/graphql/fetcher/impl/EntityDataFetcher.html[EntityDataFetcher]
|LIST (Paginated Response)
|link:{api}/org/grails/gorm/graphql/fetcher/impl/PaginatedEntityDataFetcher.html[PaginatedEntityDataFetcher]
|link:../../../api/org/grails/gorm/graphql/fetcher/impl/PaginatedEntityDataFetcher.html[PaginatedEntityDataFetcher]
|CREATE
|link:{api}/org/grails/gorm/graphql/fetcher/impl/CreateEntityDataFetcher.html[CreateEntityDataFetcher]
|link:../../../api/org/grails/gorm/graphql/fetcher/impl/CreateEntityDataFetcher.html[CreateEntityDataFetcher]
|UPDATE
|link:{api}/org/grails/gorm/graphql/fetcher/impl/UpdateEntityDataFetcher.html[UpdateEntityDataFetcher]
|link:../../../api/org/grails/gorm/graphql/fetcher/impl/UpdateEntityDataFetcher.html[UpdateEntityDataFetcher]
|DELETE
|link:{api}/org/grails/gorm/graphql/fetcher/impl/DeleteEntityDataFetcher.html[EntityDataFetcher]
|link:../../../api/org/grails/gorm/graphql/fetcher/impl/DeleteEntityDataFetcher.html[EntityDataFetcher]
|===

If the data fetcher you wish to create does not fit well in any of the above use cases, you can extend directly from link:{api}/org/grails/gorm/graphql/fetcher/DefaultGormDataFetcher.html[DefaultGormDataFetcher], which has all of the query optimization logic.
If the data fetcher you wish to create does not fit well in any of the above use cases, you can extend directly from link:../../../api/org/grails/gorm/graphql/fetcher/DefaultGormDataFetcher.html[DefaultGormDataFetcher], which has all of the query optimization logic.

All of the classes above have a constructor which takes in a link:{gormapi}org/grails/datastore/mapping/model/PersistentEntity.html[PersistentEntity]. The easiest way to get a persistent entity from a domain class is to execute the static `gormPersistentEntity` method.
All of the classes above have a constructor which takes in a link:../../../api/org/grails/datastore/mapping/model/PersistentEntity.html[PersistentEntity]. The easiest way to get a persistent entity from a domain class is to execute the static `gormPersistentEntity` method.

Using the above information, we can change the `authorByName` to extend from the link:{api}/org/grails/gorm/graphql/fetcher/impl/SingleEntityDataFetcher.html[SingleEntityDataFetcher] class because we are returning a single `Author`.
Using the above information, we can change the `authorByName` to extend from the link:../../../api/org/grails/gorm/graphql/fetcher/impl/SingleEntityDataFetcher.html[SingleEntityDataFetcher] class because we are returning a single `Author`.


[source,groovy]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ The way the provided operations respond after deleting a GORM entity instance an

== Delete Response

Delete responses are handled by a link:{api}/org/grails/gorm/graphql/response/delete/GraphQLDeleteResponseHandler.html[GraphQLDeleteResponseHandler]. The default implementation responds with an object that has a single property, `success`. You can register your own handler to override the default.
Delete responses are handled by a link:../../../api/org/grails/gorm/graphql/response/delete/GraphQLDeleteResponseHandler.html[GraphQLDeleteResponseHandler]. The default implementation responds with an object that has a single property, `success`. You can register your own handler to override the default.

For reference, see the link:https://github.com/apache/grails-core/blob/HEAD/grails-data-graphql/core/src/main/groovy/org/grails/gorm/graphql/response/delete/DefaultGraphQLDeleteResponseHandler.groovy[default handler].

Expand Down Expand Up @@ -49,7 +49,7 @@ graphQLDeleteResponseHandler(MyDeleteResponseHandler)

== Validation Error Response

Validation error responses are handled by a link:{api}/org/grails/gorm/graphql/response/errors/GraphQLErrorsResponseHandler.html[GraphQLErrorsResponseHandler].
Validation error responses are handled by a link:../../../api/org/grails/gorm/graphql/response/errors/GraphQLErrorsResponseHandler.html[GraphQLErrorsResponseHandler].

For reference, see the link:https://github.com/apache/grails-core/blob/HEAD/grails-data-graphql/core/src/main/groovy/org/grails/gorm/graphql/response/errors/DefaultGraphQLErrorsResponseHandler.groovy[default handler].

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Data binders are responsible for taking the domain argument to a create or updat

== Get The Manager

To register a data binders, you need to get a reference to the link:{api}/org/grails/gorm/graphql/binding/GraphQLDataBinderManager.html[GraphQLDataBinderManager]. If you are using the manager provided by default, how you access it will depend on whether you are using the plugin or standalone.
To register a data binders, you need to get a reference to the link:../../../api/org/grails/gorm/graphql/binding/GraphQLDataBinderManager.html[GraphQLDataBinderManager]. If you are using the manager provided by default, how you access it will depend on whether you are using the plugin or standalone.

=== Standalone

Expand Down
12 changes: 6 additions & 6 deletions grails-data-graphql/docs/src/main/docs/guide/dataFetchers.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@ specific language governing permissions and limitations
under the License.
////

This library provides a means for overriding the data fetchers used for the default provided operations. That is done through the use of a link:{api}/org/grails/gorm/graphql/fetcher/manager/GraphQLDataFetcherManager.html[GraphQLDataFetcherManager].
This library provides a means for overriding the data fetchers used for the default provided operations. That is done through the use of a link:../../../api/org/grails/gorm/graphql/fetcher/manager/GraphQLDataFetcherManager.html[GraphQLDataFetcherManager].

== Get The Manager

To register a fetcher, you need to get a reference to the link:{api}/org/grails/gorm/graphql/fetcher/manager/GraphQLDataFetcherManager.html[GraphQLDataFetcherManager]. If you are using the manager provided by default, how you access it will depend on whether you are using the plugin or standalone.
To register a fetcher, you need to get a reference to the link:../../../api/org/grails/gorm/graphql/fetcher/manager/GraphQLDataFetcherManager.html[GraphQLDataFetcherManager]. If you are using the manager provided by default, how you access it will depend on whether you are using the plugin or standalone.

=== Standalone

Expand Down Expand Up @@ -84,7 +84,7 @@ fetcherManager.registerDeletingDataFetcher(Author, new DeleteEntityDataFetcher(A
})
----

TIP: A class exists to use for soft deletes: link:{api}/org/grails/gorm/graphql/fetcher/impl/SoftDeleteEntityDataFetcher.html[SoftDeleteEntityDataFetcher]
TIP: A class exists to use for soft deletes: link:../../../api/org/grails/gorm/graphql/fetcher/impl/SoftDeleteEntityDataFetcher.html[SoftDeleteEntityDataFetcher]

There are 3 types of data fetchers that can be registered.

Expand All @@ -102,7 +102,7 @@ Reading data fetchers are designed to execute read only queries. They don't requ

== Query Optimization

All of the default data fetcher classes extend from link:{api}/org/grails/gorm/graphql/fetcher/DefaultGormDataFetcher.html[DefaultGormDataFetcher]. If you are creating your own custom data fetcher class, it is highly recommended to extend from it as well. The main reason for doing so is to take advantage of the built in query optimization. Based on what fields are requested in any given request, the default data fetchers will execute a query that will join any associations that have been requested. This feature ensures that each API call is as efficient as possible.
All of the default data fetcher classes extend from link:../../../api/org/grails/gorm/graphql/fetcher/DefaultGormDataFetcher.html[DefaultGormDataFetcher]. If you are creating your own custom data fetcher class, it is highly recommended to extend from it as well. The main reason for doing so is to take advantage of the built in query optimization. Based on what fields are requested in any given request, the default data fetchers will execute a query that will join any associations that have been requested. This feature ensures that each API call is as efficient as possible.

For example, consider the following domain structure:

Expand Down Expand Up @@ -147,11 +147,11 @@ Example generated SQL:

`select * from book b inner join author a on b.author_id = a.id where b.id = 5`

The logic for retrieving the list of properties to be joined is contained within the link:{api}/org/grails/gorm/graphql/entity/EntityFetchOptions.html[EntityFetchOptions] class. If you prefer not to extend from the default gorm data fetcher, it is possible to make use of this class in your own data fetcher.
The logic for retrieving the list of properties to be joined is contained within the link:../../../api/org/grails/gorm/graphql/entity/EntityFetchOptions.html[EntityFetchOptions] class. If you prefer not to extend from the default gorm data fetcher, it is possible to make use of this class in your own data fetcher.

=== Custom Property Data Fetchers

When adding a custom property to a domain class, it may be the case that a separate query is being executed on another domain class. Normally that query would not be able to benefit from the automatic join operations based on the requested fields in that domain class. When providing the closure to retrieve the relevant data, a second parameter is available. The second parameter to the closure will be an instance of link:{api}/org/grails/gorm/graphql/fetcher/impl/ClosureDataFetchingEnvironment.html[ClosureDataFetchingEnvironment].
When adding a custom property to a domain class, it may be the case that a separate query is being executed on another domain class. Normally that query would not be able to benefit from the automatic join operations based on the requested fields in that domain class. When providing the closure to retrieve the relevant data, a second parameter is available. The second parameter to the closure will be an instance of link:../../../api/org/grails/gorm/graphql/fetcher/impl/ClosureDataFetchingEnvironment.html[ClosureDataFetchingEnvironment].

The environment is an extension of the GraphQL Java `DataFetchingEnvironment`. In addition to everything the standard environment has, the environment also has methods for retrieving the fetch options or the list of join properties to use in your query.

Expand Down
Loading
Loading