<commit_before>//
// 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.
//
=== Customization

[CAUTION]
Only Maven projects can be customized: if using Standalone, Debian packages or the GUI installer, none of the
customizations discussed below can be applied.

Apache Syncope is designed to be as flexible as possible, to best suit the various environments
in which it can be deployed. Besides other aspects, this means that every feature and component can be extended or
replaced.

Once the project has been created from the provided Maven archetype, the generated source tree is available for either
adding new features or replacing existing components.

[[override-behavior]]
[TIP]
.Override behavior
====
As a rule of thumb, any file of the local project will take precedence over a file with the same name in the same
directory of the standard Apache Syncope release.

For example, if you place

 core/spring/src/main/java/org/apache/syncope/core/spring/security/SyncopeAuthenticationProvider.java

in the local project, this file will be picked up instead of
ifeval::["{snapshotOrRelease}" == "release"]
https://github.com/apache/syncope/blob/syncope-{docVersion}/core/spring/src/main/java/org/apache/syncope/core/spring/security/SyncopeAuthenticationProvider.java[SyncopeAuthenticationProvider^].
endif::[]
ifeval::["{snapshotOrRelease}" == "snapshot"]
https://github.com/apache/syncope/blob/master/core/spring/src/main/java/org/apache/syncope/core/spring/security/SyncopeAuthenticationProvider.java[SyncopeAuthenticationProvider^].
endif::[]

The same happens with resources as images or HTML files; if you place

 console/src/main/resources/org/apache/syncope/client/console/pages/BasePage.html

in the local project, this file will be picked up instead of
ifeval::["{snapshotOrRelease}" == "release"]
https://github.com/apache/syncope/blob/syncope-{docVersion}/client/console/src/main/resources/org/apache/syncope/client/console/pages/BasePage.html[BasePage.html^].
endif::[]
ifeval::["{snapshotOrRelease}" == "snapshot"]
https://github.com/apache/syncope/blob/master/client/console/src/main/resources/org/apache/syncope/client/console/pages/BasePage.html[BasePage.html^].
endif::[]

This general behavior might have exceptions, as highlighted below.
====

In general, the Embedded Mode (see the
ifeval::["{backend}" == "html5"]
http://syncope.apache.org/docs/getting-started.html[Apache Syncope Getting Started Guide]
endif::[]
ifeval::["{backend}" == "pdf"]
http://syncope.apache.org/docs/getting-started.pdf[Apache Syncope Getting Started Guide]
endif::[]
for details) allows the user to work comfortably from a single workstation, with no need of additional setup; it is
effectively implemented as the `all`
https://maven.apache.org/guides/introduction/introduction-to-profiles.html[Maven profile^], where the available optional
components and extensions are enabled. +
When deploying the generated WAR artifacts into an external <<javaee-container>> however, the required components and
extensions need to be explicitly selected and enabled, as shown in the following text.

[[deployment-directories]]
.Deployment directories
****
Apache Syncope needs three base directories to be defined:

* bundles - where the <<external-resources,connector bundles>> are stored;
* log - where all the system logs are written;
* conf (optional) - where configuration files are located, if overriding the default values is needed.

[WARNING]
The `bundles` directory should only contain connector bundle JAR files. +
The presence of any other file might cause the unavailability of any connector bundle in Apache Syncope.

For reference, the suggested directory layout can be created as follows:

....
$ mkdir /opt/syncope
$ mkdir /opt/syncope/bundles
$ mkdir /opt/syncope/log
$ mkdir /opt/syncope/conf
....
****

The WAR artifacts are generated by running the Maven command (with reference to the suggested directory layout):

....
mvn clean verify \
  -Dconf.directory=/opt/syncope/conf \
  -Dbundles.directory=/opt/syncope/bundles \
  -Dlog.directory=/opt/syncope/log
....

After downloading all of the dependencies that are needed, three WAR files will be produced:

. `core/target/syncope.war`
. `console/target/syncope-console.war`
. `enduser/target/syncope-enduser.war`

If no failures are encountered, your basic Apache Syncope project is now ready to be deployed.

[[customization-core]]
==== Core

[CAUTION]
When providing custom Java classes implementing the defined interfaces or extending the existing
implementations, their package *must* be rooted under `org.apache.syncope.core`, otherwise they will not be available
at runtime.

Besides replacing existing classes as explained <<override-behavior,above>>, new implementations can be provided under
`core/src/main/java` for the following components:

* <<propagationactions,propagation>>, <<pushactions,push>>, <<pullactions,pull>> and <<logicactions,logic>> actions
* <<push-correlation-rules,push>> / <<pull-correlation-rules,pull>> correlation rules
* <<pull-mode,reconciliation filter builders>>
* <<tasks-custom,custom tasks>>
* <<reportlets,reportlets>>
* <<account-rules,account>> and <<password-rules,password>> rules for policies
* <<plain,plain schema validators>>
* <<mapping,mapping item transformers>>
* <<virtual-attribute-cache,virtual attribute cache>>
* <<workflow-adapters,workflow adapters>>
* <<provisioning-managers,provisioning managers>><commit_msg>Instructions on how to enable JPDA debug in embedded mode<commit_after>//
// 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.
//
=== Customization

[CAUTION]
Only Maven projects can be customized: if using Standalone, Debian packages or the GUI installer, none of the
customizations discussed below can be applied.

Apache Syncope is designed to be as flexible as possible, to best suit the various environments
in which it can be deployed. Besides other aspects, this means that every feature and component can be extended or
replaced.

Once the project has been created from the provided Maven archetype, the generated source tree is available for either
adding new features or replacing existing components.

[[override-behavior]]
[TIP]
.Override behavior
====
As a rule of thumb, any file of the local project will take precedence over a file with the same name in the same
directory of the standard Apache Syncope release.

For example, if you place

 core/spring/src/main/java/org/apache/syncope/core/spring/security/SyncopeAuthenticationProvider.java

in the local project, this file will be picked up instead of
ifeval::["{snapshotOrRelease}" == "release"]
https://github.com/apache/syncope/blob/syncope-{docVersion}/core/spring/src/main/java/org/apache/syncope/core/spring/security/SyncopeAuthenticationProvider.java[SyncopeAuthenticationProvider^].
endif::[]
ifeval::["{snapshotOrRelease}" == "snapshot"]
https://github.com/apache/syncope/blob/master/core/spring/src/main/java/org/apache/syncope/core/spring/security/SyncopeAuthenticationProvider.java[SyncopeAuthenticationProvider^].
endif::[]

The same happens with resources as images or HTML files; if you place

 console/src/main/resources/org/apache/syncope/client/console/pages/BasePage.html

in the local project, this file will be picked up instead of
ifeval::["{snapshotOrRelease}" == "release"]
https://github.com/apache/syncope/blob/syncope-{docVersion}/client/console/src/main/resources/org/apache/syncope/client/console/pages/BasePage.html[BasePage.html^].
endif::[]
ifeval::["{snapshotOrRelease}" == "snapshot"]
https://github.com/apache/syncope/blob/master/client/console/src/main/resources/org/apache/syncope/client/console/pages/BasePage.html[BasePage.html^].
endif::[]

This general behavior might have exceptions, as highlighted below.
====

In general, the Embedded Mode (see the
ifeval::["{backend}" == "html5"]
http://syncope.apache.org/docs/getting-started.html[Apache Syncope Getting Started Guide]
endif::[]
ifeval::["{backend}" == "pdf"]
http://syncope.apache.org/docs/getting-started.pdf[Apache Syncope Getting Started Guide]
endif::[]
for details) allows the user to work comfortably from a single workstation, with no need of additional setup; it is
effectively implemented as the `all`
https://maven.apache.org/guides/introduction/introduction-to-profiles.html[Maven profile^], where the available optional
components and extensions are enabled. +
When deploying the generated WAR artifacts into an external <<javaee-container>> however, the required components and
extensions need to be explicitly selected and enabled, as shown in the following text.

[[deployment-directories]]
.Deployment directories
****
Apache Syncope needs three base directories to be defined:

* bundles - where the <<external-resources,connector bundles>> are stored;
* log - where all the system logs are written;
* conf (optional) - where configuration files are located, if overriding the default values is needed.

[WARNING]
The `bundles` directory should only contain connector bundle JAR files. +
The presence of any other file might cause the unavailability of any connector bundle in Apache Syncope.

For reference, the suggested directory layout can be created as follows:

....
$ mkdir /opt/syncope
$ mkdir /opt/syncope/bundles
$ mkdir /opt/syncope/log
$ mkdir /opt/syncope/conf
....
****

The WAR artifacts are generated by running the Maven command (with reference to the suggested directory layout):

....
mvn clean verify \
  -Dconf.directory=/opt/syncope/conf \
  -Dbundles.directory=/opt/syncope/bundles \
  -Dlog.directory=/opt/syncope/log
....

After downloading all of the dependencies that are needed, three WAR files will be produced:

. `core/target/syncope.war`
. `console/target/syncope-console.war`
. `enduser/target/syncope-enduser.war`

If no failures are encountered, your basic Apache Syncope project is now ready to be deployed.

[[embedded-debug]]
[TIP]
.JPDA Debug in Embedded Mode
====
The Java™ Platform Debugger Architecture (http://docs.oracle.com/javase/8/docs/technotes/guides/jpda/index.html[JPDA^])
is a collection of APIs aimed to help with debugging Java code.

Enhancing the `embedded` profile of the `enduser` module to enable the JPDA socket is quite
straightforward: just add the `<profile>` below to `enduser/pom.xml`:

[source,xml,subs="verbatim,attributes"]
----
<profile>
  <id>debug</id>

  <build>
    <plugin>
      <plugin>
        <groupId>org.codehaus.cargo</groupId>
        <artifactId>cargo-maven2-plugin</artifactId>
        <inherited>true</inherited>
        <configuration>
          <configuration>
            <properties>
              <cargo.jvmargs>
              -Xdebug
              -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n
              -noverify -XX:+CMSClassUnloadingEnabled
              -XX:+UseConcMarkSweepGC -Xmx1024m -Xms512m
              </cargo.jvmargs>
            </properties>
          </configuration>
        </configuration>
      </plugin>
    </plugins>
  </build>
</profile>
----

At this point your favorite IDE can be attached to the port `8000`; please note that you might need to add
`-XX:MaxPermSize=512m` to `<cargo.jvmargs>` in order to run with JDK 7.
====

[[customization-core]]
==== Core

[CAUTION]
When providing custom Java classes implementing the defined interfaces or extending the existing
implementations, their package *must* be rooted under `org.apache.syncope.core`, otherwise they will not be available
at runtime.

Besides replacing existing classes as explained <<override-behavior,above>>, new implementations can be provided under
`core/src/main/java` for the following components:

* <<propagationactions,propagation>>, <<pushactions,push>>, <<pullactions,pull>> and <<logicactions,logic>> actions
* <<push-correlation-rules,push>> / <<pull-correlation-rules,pull>> correlation rules
* <<pull-mode,reconciliation filter builders>>
* <<tasks-custom,custom tasks>>
* <<reportlets,reportlets>>
* <<account-rules,account>> and <<password-rules,password>> rules for policies
* <<plain,plain schema validators>>
* <<mapping,mapping item transformers>>
* <<virtual-attribute-cache,virtual attribute cache>>
* <<workflow-adapters,workflow adapters>>
* <<provisioning-managers,provisioning managers>>
{'fraction_non_alphanumeric': 0.10637833114897335, 'fraction_numerical': 0.002257171981942624, 'mean_word_length': 4.715771951727008, 'pattern_counts': {'":': 0, '<': 105, '<?xml version=': 0, '>': 105, 'https://': 10, 'lorem ipsum': 0, 'www.': 2, 'xml': 2}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7153436', 'n_tokens_mistral': 3808, 'n_tokens_neox': 3685, 'n_words': 1363}