Skip to content

[docs] Java high-level REST client : clean up #28703

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 20, 2018
Merged

[docs] Java high-level REST client : clean up #28703

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
594edd1
Consistent doc title with the ES docs
olcbean Feb 15, 2018
6daa5da
Merge branch 'master' into hlrc_update_aliases_doc
Feb 20, 2018
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
39 changes: 28 additions & 11 deletions ...el/src/test/java/org/elasticsearch/client/documentation/IndicesClientDocumentationIT.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -752,17 +752,31 @@ public void testUpdateAliases() throws Exception {
{
// tag::update-aliases-request
Copy link
Member

@cbuescher cbuescher Feb 19, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm curious why the sections were all called "update-aliases-*" before. The request name (IndicesAliasesRequest) doesn't seem to have changed recently. Maybe it would make sense to update the tags (and the corresponding includes) as well now?

Copy link
Member

@javanna javanna Feb 19, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is on me, it's a common inconsistency between our Client method names, our request names, and how the API are called in our SPEC. We are now following the name from the SPEC when naming the new methods. But we leave requests unchanged to reduce noise and not impact bw comp too much at this stage. Let's leave the tags as they are?

IndicesAliasesRequest request = new IndicesAliasesRequest(); // <1>
AliasActions aliasAction = new AliasActions(AliasActions.Type.ADD).index("index1").alias("alias1"); // <2>
AliasActions aliasAction =
new AliasActions(AliasActions.Type.ADD)
.index("index1")
.alias("alias1"); // <2>
Copy link
Member

@cbuescher cbuescher Feb 19, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

+1, I'm in favour of changing the indentation.
Unfortunately we don't seem to have a way to catch accidental reformatting of these sections in the future. Just a remark, nothing to change here I think.

Copy link
Contributor Author

@olcbean olcbean Feb 19, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately, we don't. The only way to do that is to use the //@formatter:off for the snippet sections but the tags are not activated by default ( at least in eclipse, but I would guess in IntelliJ is the same). I would say one more reason to consider using a simple formatter for ES ;)

request.addAliasAction(aliasAction); // <3>
// end::update-aliases-request

// tag::update-aliases-request2
AliasActions addIndexAction = new AliasActions(AliasActions.Type.ADD).index("index1").alias("alias1")
.filter("{\"term\":{\"year\":2016}}"); // <1>
AliasActions addIndicesAction = new AliasActions(AliasActions.Type.ADD).indices("index1", "index2").alias("alias2")
.routing("1"); // <2>
AliasActions removeAction = new AliasActions(AliasActions.Type.REMOVE).index("index3").alias("alias3"); // <3>
AliasActions removeIndexAction = new AliasActions(AliasActions.Type.REMOVE_INDEX).index("index4"); // <4>
AliasActions addIndexAction =
new AliasActions(AliasActions.Type.ADD)
.index("index1")
.alias("alias1")
.filter("{\"term\":{\"year\":2016}}"); // <1>
AliasActions addIndicesAction =
new AliasActions(AliasActions.Type.ADD)
.indices("index1", "index2")
.alias("alias2")
.routing("1"); // <2>
AliasActions removeAction =
new AliasActions(AliasActions.Type.REMOVE)
.index("index3")
.alias("alias3"); // <3>
AliasActions removeIndexAction =
new AliasActions(AliasActions.Type.REMOVE_INDEX)
.index("index4"); // <4>
// end::update-aliases-request2

// tag::update-aliases-request-timeout
Expand All @@ -775,21 +789,24 @@ public void testUpdateAliases() throws Exception {
// end::update-aliases-request-masterTimeout

// tag::update-aliases-execute
IndicesAliasesResponse indicesAliasesResponse = client.indices().updateAliases(request);
IndicesAliasesResponse indicesAliasesResponse =
client.indices().updateAliases(request);
// end::update-aliases-execute

// tag::update-aliases-response
boolean acknowledged = indicesAliasesResponse.isAcknowledged(); // <1>
// end::update-aliases-response
assertTrue(acknowledged);
}

{
IndicesAliasesRequest request = new IndicesAliasesRequest(); // <1>
AliasActions aliasAction = new AliasActions(AliasActions.Type.ADD).index("index1").alias("async"); // <2>
IndicesAliasesRequest request = new IndicesAliasesRequest();
AliasActions aliasAction = new AliasActions(AliasActions.Type.ADD).index("index1").alias("async");
request.addAliasAction(aliasAction);

// tag::update-aliases-execute-listener
ActionListener<IndicesAliasesResponse> listener = new ActionListener<IndicesAliasesResponse>() {
ActionListener<IndicesAliasesResponse> listener =
new ActionListener<IndicesAliasesResponse>() {
@Override
public void onResponse(IndicesAliasesResponse indicesAliasesResponse) {
// <1>
Expand Down
4 changes: 2 additions & 2 deletions docs/java-rest/high-level/indices/update_aliases.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
[[java-rest-high-update-aliases]]
Copy link
Member

@cbuescher cbuescher Feb 19, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should the section shortcut also change to "indices-aliases"?

Copy link
Member

@javanna javanna Feb 19, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no please :) it does not matter that much, and both names are correct :)

Copy link
Member

@javanna javanna Feb 19, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

one more inconsistency not mentioned above: the way we reference our API in our docs may differ from the request names, the client method names and the api names in our SPEC :) here we try to name pages the same as how they are named in the es reference

=== Update Aliases API
=== Index Aliases API

[[java-rest-high-update-aliases-request]]
Copy link
Member

@cbuescher cbuescher Feb 19, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

same here

==== Indices Aliases Request

The Update Aliases API allows aliasing an index with a name, with all APIs
The Index Aliases API allows aliasing an index with a name, with all APIs
automatically converting the alias name to the actual index name.

An `IndicesAliasesRequest` must have at least one `AliasActions`:
Expand Down