You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@syncope.apache.org by il...@apache.org on 2016/08/25 12:48:23 UTC
[1/2] syncope git commit: Adding more external Javadoc refs
Repository: syncope
Updated Branches:
refs/heads/master d9848ecd6 -> 270488da6
Adding more external Javadoc refs
Project: http://git-wip-us.apache.org/repos/asf/syncope/repo
Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/08800221
Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/08800221
Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/08800221
Branch: refs/heads/master
Commit: 088002211e8b7dbee48e0136ab9430bb23a35d3c
Parents: d9848ec
Author: Francesco Chicchiricc� <il...@apache.org>
Authored: Thu Aug 25 13:23:39 2016 +0200
Committer: Francesco Chicchiricc� <il...@apache.org>
Committed: Thu Aug 25 13:23:39 2016 +0200
----------------------------------------------------------------------
pom.xml | 7 +++++++
1 file changed, 7 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/syncope/blob/08800221/pom.xml
----------------------------------------------------------------------
diff --git a/pom.xml b/pom.xml
index 9d3d4a4..9bc153e 100644
--- a/pom.xml
+++ b/pom.xml
@@ -1971,6 +1971,13 @@ under the License.
<link>http://docs.oracle.com/javaee/7/api/</link>
<link>http://www.slf4j.org/api/</link>
<link>http://connid.tirasa.net/apidocs/1.4/</link>
+ <link>http://cxf.apache.org/javadoc/latest-3.1.x/</link>
+ <link>http://fasterxml.github.io/jackson-core/javadoc/2.8/</link>
+ <link>http://fasterxml.github.io/jackson-databind/javadoc/2.8/</link>
+ <link>http://fasterxml.github.io/jackson-annotations/javadoc/2.8/</link>
+ <link>http://fasterxml.github.io/jackson-dataformat-xml/javadoc/2.8/</link>
+ <link>http://fasterxml.github.io/jackson-dataformat-yaml/javadoc/2.8/</link>
+ <link>http://fasterxml.github.io/jackson-datatype-joda/javadoc/2.8/</link>
<link>http://camel.apache.org/maven/current/camel-core/apidocs/</link>
<link>http://camel.apache.org/maven/current/camel-spring/apidocs/</link>
<link>https://ci.apache.org/projects/wicket/apidocs/7.x/</link>
[2/2] syncope git commit: [SYNCOPE-700] RESTful services
Posted by il...@apache.org.
[SYNCOPE-700] RESTful services
Project: http://git-wip-us.apache.org/repos/asf/syncope/repo
Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/270488da
Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/270488da
Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/270488da
Branch: refs/heads/master
Commit: 270488da6c60c575f4646b0c5e9a9554d47b9b15
Parents: 0880022
Author: Francesco Chicchiricc� <il...@apache.org>
Authored: Thu Aug 25 14:48:14 2016 +0200
Committer: Francesco Chicchiricc� <il...@apache.org>
Committed: Thu Aug 25 14:48:14 2016 +0200
----------------------------------------------------------------------
.../asciidoc/images/restReferenceLoggerRead.png | Bin 68071 -> 0 bytes
.../images/restReferenceLoggerUpdate.png | Bin 63936 -> 0 bytes
.../images/restSchemaReferenceLogger.png | Bin 203689 -> 0 bytes
.../reference-guide/architecture/core.adoc | 6 +-
.../restfulservices.adoc | 249 +++++++++++++++++++
.../restfulservices/client-library.adoc | 60 -----
.../restfulservices/restful-reference.adoc | 34 ---
.../restfulservices/restful-services.adoc | 30 ---
.../workingwithapachesyncope.adoc | 2 +-
9 files changed, 253 insertions(+), 128 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/syncope/blob/270488da/src/main/asciidoc/images/restReferenceLoggerRead.png
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/images/restReferenceLoggerRead.png b/src/main/asciidoc/images/restReferenceLoggerRead.png
deleted file mode 100644
index b9c0152..0000000
Binary files a/src/main/asciidoc/images/restReferenceLoggerRead.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/syncope/blob/270488da/src/main/asciidoc/images/restReferenceLoggerUpdate.png
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/images/restReferenceLoggerUpdate.png b/src/main/asciidoc/images/restReferenceLoggerUpdate.png
deleted file mode 100644
index 58ac593..0000000
Binary files a/src/main/asciidoc/images/restReferenceLoggerUpdate.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/syncope/blob/270488da/src/main/asciidoc/images/restSchemaReferenceLogger.png
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/images/restSchemaReferenceLogger.png b/src/main/asciidoc/images/restSchemaReferenceLogger.png
deleted file mode 100644
index 44b85a6..0000000
Binary files a/src/main/asciidoc/images/restSchemaReferenceLogger.png and /dev/null differ
http://git-wip-us.apache.org/repos/asf/syncope/blob/270488da/src/main/asciidoc/reference-guide/architecture/core.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/architecture/core.adoc b/src/main/asciidoc/reference-guide/architecture/core.adoc
index 7252da3..c46f6ec 100644
--- a/src/main/asciidoc/reference-guide/architecture/core.adoc
+++ b/src/main/asciidoc/reference-guide/architecture/core.adoc
@@ -29,10 +29,10 @@ The primary way to consume Core services is the https://en.wikipedia.org/wiki/Re
interface, which enables full access to all the features provided.
This interface enables third-party applications, written in any programming language, to consume IdM services.
-The rich pre-defined set of endpoints can be extended by adding new ones, which might be needed on a given Apache
-Syncope deployment to complement the native features with domain-specific operations.
+The rich pre-defined set of endpoints can be <<extensions,extended>> by adding new ones, which might be needed on a
+given Apache Syncope deployment to complement the native features with domain-specific operations.
-An <<swagger,extension>> is available, providing full http://swagger.io/[Swagger^] features,
+An <<swagger,extension>> is also available, providing full http://swagger.io/[Swagger^] features,
which enables in-browser access to all the REST endpoints defined.
At a technical level, the RESTful interface is a fully-compliant
http://git-wip-us.apache.org/repos/asf/syncope/blob/270488da/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc
new file mode 100644
index 0000000..b59aa54
--- /dev/null
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices.adoc
@@ -0,0 +1,249 @@
+//
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements. See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership. The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License. You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied. See the License for the
+// specific language governing permissions and limitations
+// under the License.
+//
+=== RESTful services
+
+All the features provided by the <<core>> are available as RESTful services.
+
+The base URL for invoking such services is normally set as
+
+[source]
+--
+protocol://host:port/syncope/rest/
+--
+
+where `protocol`, `host` and `port` reflect your Java EE container installation.
+
+[NOTE]
+.REST Reference
+====
+A complete REST reference generated from https://en.wikipedia.org/wiki/Web_Application_Description_Language[WADL^] is
+http://syncope.apache.org/rest/2.0/index.html[published^] as well as made available with each deployment at
+
+[source]
+--
+protocol://host:port/syncope/
+--
+
+where `protocol`, `host` and `port` reflect your Java EE container installation.
+====
+
+[TIP]
+The <<swagger,Swagger extension>> might be greatly helpful when working with RESTful services.
+
+==== Client Library
+
+The Java client library is meant for simplifying the interaction with the <<core>> by hiding the underlying HTTP
+communication details and providing native methods and payload objects.
+
+The library is available as Maven artifact:
+
+[source,xml,subs="verbatim,attributes"]
+----
+<dependency>
+ <groupId>org.apache.syncope.client</groupId>
+ <artifactId>syncope-client-lib</artifactId>
+ <version>{docVersion}</version>
+</dependency>
+----
+
+ifeval::["{snapshotOrRelease}" == "snapshot"]
+
+[WARNING]
+====
+Do not forget to add the following repository to your `pom.xml`:
+
+[source,xml]
+----
+<repository>
+ <id>ASF</id>
+ <url>https://repository.apache.org/content/repositories/snapshots/</url>
+ <snapshots>
+ <enabled>true</enabled>
+ </snapshots>
+</repository>
+----
+====
+
+endif::[]
+
+[discrete]
+===== Initialization
+
+You need first to build an instance of `SyncopeClientFactoryBean` by providing the deployment base URL, as follows:
+
+[source,java]
+----
+SyncopeClientFactoryBean clientFactory = new SyncopeClientFactoryBean().
+ setAddress("http://localhost:9080/syncope/rest/");
+----
+
+You might also select a specific <<domains,domain>> - other than `Master`, choose to exchange XML payloads - rather
+than JSON (default), or to select the
+https://en.wikipedia.org/wiki/HTTP_compression[HTTP compression^] (more options in the
+http://syncope.apache.org/apidocs/2.0/org/apache/syncope/client/lib/SyncopeClientFactoryBean.html[Javadoc^]):
+
+[source,java]
+----
+SyncopeClientFactoryBean clientFactory = new SyncopeClientFactoryBean().
+ setAddress("http://localhost:9080/syncope/rest/").
+ setDomain("Two").
+ setContentType(SyncopeClientFactoryBean.ContentType.XML).
+ setUseCompression(true);
+----
+
+At this point an instance of `SyncopeClient` can be obtained by passing the login credentials via:
+
+[source,java]
+----
+SyncopeClient client = clientFactory.create("admin", "password");
+----
+
+Or you can combine into a single statement as:
+
+[source,java]
+----
+SyncopeClient client = new SyncopeClientFactoryBean().
+ setAddress("http://localhost:9080/syncope/rest/").
+ create("admin", "password");
+----
+
+[discrete]
+===== Usage
+
+Select one of the
+http://syncope.apache.org/apidocs/2.0/org/apache/syncope/common/rest/api/service/package-summary.html[RESTful services^]
+and invoke one of the available methods:
+
+[source,java]
+----
+LoggerService loggerService = client.getService(LoggerService.class);
+
+LoggerTO loggerTO = loggerService.read(LoggerType.LOG, "org.apache.syncope.core.connid");
+loggerTO.setLevel(LoggerLevel.DEBUG);
+
+loggerService.update(LoggerType.LOG, loggerTO);
+----
+
+[NOTE]
+More RESTful services could be available besides the
+http://syncope.apache.org/apidocs/2.0/org/apache/syncope/common/rest/api/service/package-summary.html[default set^],
+as there might be <<extensions,extensions>> installed in the given deployment; the
+<<apache-camel-provisioning-engine>> provides the
+http://syncope.apache.org/apidocs/2.0/org/apache/syncope/common/rest/api/service/CamelRouteService.html[CamelRouteService^],
+for instance.
+
+[TIP]
+Advanced REST features are also available from `SyncopeClient` instances: check
+http://syncope.apache.org/apidocs/2.0/org/apache/syncope/client/lib/SyncopeClient.html[the javadoc^]
+for more information.
+
+.Search for users, groups or any objects
+====
+All search operations return
+http://syncope.apache.org/apidocs/2.0/org/apache/syncope/common/lib/to/PagedResult.html[paged result handlers^]
+which can be exploited both for getting the actual results and for extrapolating pagination coordinates.
+
+[source,java]
+----
+UserService userService = client.getService(UserService.class);
+
+int count = userService.search(new AnyQuery.Builder().page(0).size(0).build()).getTotalCount(); // <1>
+
+PagedResult<UserTO> matchingUsers = userService.search(
+ new AnyQuery.Builder().realm(SyncopeConstants.ROOT_REALM).
+ fiql(SyncopeClient.getUserSearchConditionBuilder().is("username").equalTo("ros*ini").query()).
+ build()); // <2>
+
+PagedResult<UserTO> matchingUsers = userService.search(
+ new AnyQuery.Builder().realm(SyncopeConstants.ROOT_REALM).
+ fiql(SyncopeClient.getUserSearchConditionBuilder().isNull("loginDate").query()).
+ build()); // <3>
+
+PagedResult<UserTO> matchingUsers = userService.search(
+ new AnyQuery.Builder().realm(SyncopeConstants.ROOT_REALM).
+ fiql(SyncopeClient.getUserSearchConditionBuilder().inRoles("Other").query()).
+ build()); // <4>
+
+AnyObjectService anyObjectService = client.getService(AnyObjectService.class);
+
+PagedResult<AnyObjectTO> matchingAnyObjects = anyObjectService.search(
+ new AnyQuery.Builder().realm(SyncopeConstants.ROOT_REALM).
+ fiql(SyncopeClient.getAnyObjectSearchConditionBuilder("PRINTER").query()).
+ build()); // <5>
+
+GroupService groupService = client.getService(GroupService.class);
+
+PagedResult<GroupTO> matchingGroups = groupService.search(
+ new AnyQuery.Builder().realm("/even/two").page(3).size(150).
+ fiql(SyncopeClient.getGroupSearchConditionBuilder().isAssignable().
+ and("name").equalTo("palo*").query()).
+ build()); // <6>
+----
+<1> get the total number of users available in the given deployment (and <<domains,domain>>)
+<2> get users in the root realm with username matching the provided wildcard expression
+<3> get users in the root realm with no values for `loginDate`, e.g. that have never authenticated to the
+given deployment
+<4> get users in the root realm with <<roles,role>> `Other` assigned
+<5> get all any objects in the root realm with <<anytype,type>> `PRINTER`
+<6> get all groups that can be assigned to users or any objects in the `/even/two` realm - third page of the result,
+where each page contains 150 items
+====
+
+.Delete several users at once
+====
+[source,java]
+----
+UserService userService = client.getService(UserService.class);
+
+BulkAction bulkAction = new BulkAction();
+bulkAction.setType(BulkAction.Type.DELETE);
+
+final int pageSize = 100;
+final int count = userService.search(
+ new AnyQuery.Builder().page(0).size(0).build()).getTotalCount(); // <1>
+for (int page = 1; page <= (count / pageSize) + 1; page++) {
+ for (UserTO user : userService.search(
+ new AnyQuery.Builder().page(page).size(pageSize).build()).getResult()) { // <2>
+
+ bulkAction.getTargets().add(user.getKey()); // <3>
+ }
+}
+
+BulkActionResult bulkResult = userService.bulk(bulkAction).
+ readEntity(BulkActionResult.class); // <4>
+Map<String, BulkActionResult.Status> results = bulkResult.getResults(); // <5>
+----
+<1> get the total number of users available in the given deployment (and <<domains,domain>>)
+<2> loop throgh all users available, using paginated search
+<3> add each user to the bulk action
+<4> execute the `DELETE` bulk action
+<5> examine the bulk action results
+====
+
+.Self-read own profile information
+====
+[source,java]
+----
+Pair<Map<String, Set<String>>, UserTO> self = client.self();
+UserTO userTO = self.getRight(); // <1>
+Map<String, Set<String>> realm2entitlements = self.getLeft(); // <2>
+----
+<1> http://syncope.apache.org/apidocs/2.0/org/apache/syncope/common/lib/to/UserTO.html[UserTO^] of the requesting user
+<2> for each <<realms,realm>>, the owned <<entitlements,entitlements>>
+====
http://git-wip-us.apache.org/repos/asf/syncope/blob/270488da/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices/client-library.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices/client-library.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices/client-library.adoc
deleted file mode 100644
index 018027e..0000000
--- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices/client-library.adoc
+++ /dev/null
@@ -1,60 +0,0 @@
-//
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-//
-
-==== Client library
-The Apache Syncope client library, as suggested, is a Java client to work with the Apache Syncope core.
-
-===== Maven dependency
-[source,xml,subs="verbatim,attributes"]
-----
-<dependency>
- <groupId>org.apache.syncope.client</groupId>
- <artifactId>syncope-client-lib</artifactId>
- <version>{docVersion}</version>
-</dependency>
-----
-
-===== Instantiation
-Basically, all you need is to obtain a SyncopeClient instance via the following statement in order
-to set the base REST URL and credentials:
-
-[source,java]
-----
-SyncopeClient client = new SyncopeClientFactoryBean().
- setAddress("http://localhost:9080/syncope/rest/").
- create("admin", "password");
-----
-
-and you get enabled for any kind of REST service interaction with Apache Syncope.
-You can read the http://syncope.apache.org/apidocs/1.2/org/apache/syncope/common/services/package-summary.html[javadoc]
-page for a documented list of available REST services in Apache Syncope.
-
-===== Usage example
-Below a snippet that shows how to use the SyncopeClient to update the logger configuration.
-[source,java]
-----
-SyncopeClient client = new SyncopeClientFactoryBean().
- setAddress("http://localhost:9080/syncope/rest/").
- create("admin", "password");
-LoggerService loggerService = client.getService(LoggerService.class);
-
-LoggerTO loggerTO = loggerService.read(LoggerType.LOG, "org.apache.syncope.core.connid");
-loggerTO.setLevel(LoggerLevel.DEBUG);
-loggerService.update(LoggerType.LOG, loggerTO);
-----
http://git-wip-us.apache.org/repos/asf/syncope/blob/270488da/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices/restful-reference.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices/restful-reference.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices/restful-reference.adoc
deleted file mode 100644
index c19ef19..0000000
--- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices/restful-reference.adoc
+++ /dev/null
@@ -1,34 +0,0 @@
-//
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-//
-==== RESTful reference
-If you want to read from the complete descriptive REST reference the URL you need is
-[source]
---
-http://localhost:9080/syncope/
---
-where you can see all the REST resources with their description, the parameters and the reference to the schema,
-so you are able to see which attributes and which type are needed to the every service.
-Following the same example as before, below two images to show the REST resources of the logger service and another one
-for the reference to the schema:
-
-image::restReferenceLoggerRead.png[restReferenceLoggerRead]
-
-image::restReferenceLoggerUpdate.png[restReferenceLoggerUpdate]
-
-image::restSchemaReferenceLogger.png[restSchemaReferenceLogger]
http://git-wip-us.apache.org/repos/asf/syncope/blob/270488da/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices/restful-services.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices/restful-services.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices/restful-services.adoc
deleted file mode 100644
index 758bb74..0000000
--- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/restfulservices/restful-services.adoc
+++ /dev/null
@@ -1,30 +0,0 @@
-//
-// Licensed to the Apache Software Foundation (ASF) under one
-// or more contributor license agreements. See the NOTICE file
-// distributed with this work for additional information
-// regarding copyright ownership. The ASF licenses this file
-// to you under the Apache License, Version 2.0 (the
-// "License"); you may not use this file except in compliance
-// with the License. You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing,
-// software distributed under the License is distributed on an
-// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
-// KIND, either express or implied. See the License for the
-// specific language governing permissions and limitations
-// under the License.
-//
-=== RESTful services
-The RESTful services is the way how the Syncope core web application receives the input from the clients.
-This layer, developed in http://cxf.apache.org/docs/jax-rs.html[Apache CXF 2.0], is usually reachable under the
-root context of the deployment.
-[source]
---
-http://localhost:9080/syncope/rest
---
-
-include::restful-reference.adoc[]
-
-include::client-library.adoc[]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/syncope/blob/270488da/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc b/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc
index 561c3b4..29b817a 100644
--- a/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc
+++ b/src/main/asciidoc/reference-guide/workingwithapachesyncope/workingwithapachesyncope.adoc
@@ -32,7 +32,7 @@ include::adminconsole/adminconsole.adoc[]
include::cli/cli.adoc[]
-include::restfulservices/restful-services.adoc[]
+include::restfulservices.adoc[]
=== Customization