http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/bundles/discovery-api-and-impl.md ---------------------------------------------------------------------- diff --git a/content/documentation/bundles/discovery-api-and-impl.md b/content/documentation/bundles/discovery-api-and-impl.md index 10abaf9..e2a60b2 100644 --- a/content/documentation/bundles/discovery-api-and-impl.md +++ b/content/documentation/bundles/discovery-api-and-impl.md @@ -1,10 +1,13 @@ -title=Discovery API and its implementations -type=page +title=TODO title for discovery-api-and-impl.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Discovery API and its implementations In many situations a particular Sling-based deployment consists of several Sling instances: -typically a number of instances would form a `cluster` that share a common content repository - +typically a number of instances would form a `cluster` that share a common content repository - in other situations, or additionally, instances might be loosely coupled, each with their own repository. The `discovery-api` bundle introduces an abstraction for such scenarios called `topology`. It provides @@ -46,7 +49,7 @@ is always part of a cluster (even if the cluster consists of only one instance). There are no further assumption made on the structure of a topology. -If different clusters in the topology should represent different 'types of clusters' (eg a publish or an author cluster), +If different clusters in the topology should represent different 'types of clusters' (eg a publish or an author cluster), then that is not explicitly handled by the discovery API. Instead, applications can define properties on each instance that model such cluster types or other aspects. @@ -60,13 +63,13 @@ deal with work that must be guaranteed to only execute on one (but any) instance Additionally each cluster (`ClusterView`) orders its instances in a stable list: each newly joined instances is added at the end of the list and retains its order in the list as long as it doesn't leave the cluster. This can be used -to distribute "singleton" work amongst the cluster to more than just the leader. +to distribute "singleton" work amongst the cluster to more than just the leader. ## Topology Changes -The `DiscoveryService` provides access to the currently valid `TopologyView`. Additionally, applications can +The `DiscoveryService` provides access to the currently valid `TopologyView`. Additionally, applications can register a `TopologyEventListener` and thus be informed about any changes in the topology. Whenever the discovery -service detects that an instance is no longer responding or has newly joined, or a new leader has been elected, +service detects that an instance is no longer responding or has newly joined, or a new leader has been elected, it sends a `TOPOLOGY_CHANGING` event, starts settling the change within the topology (i.e. making sure everybody else in the topology agrees with the change) and finally sends a `TOPOLOGY_CHANGED` event with the new topology. @@ -75,23 +78,23 @@ Additionally, when "only" properties have changed, a `PROPERTIES_CHANGED` event Note that the detection of topology (or properties) changes will incur a delay which is implementation dependent. -The following is an example of a listener. Note that the binding is done automatically by OSGi, as soon as a +The following is an example of a listener. Note that the binding is done automatically by OSGi, as soon as a `TopologyEventListener` is registered. -import org.apache.felix.scr.annotations.Component; -import org.apache.felix.scr.annotations.Service; -import org.apache.sling.discovery.TopologyEvent; -import org.apache.sling.discovery.TopologyEventListener; + import org.apache.felix.scr.annotations.Component; + import org.apache.felix.scr.annotations.Service; + import org.apache.sling.discovery.TopologyEvent; + import org.apache.sling.discovery.TopologyEventListener; -@Component -@Service(value = { TopologyEventListener.class }) -public class MyTopologyEventListener implements TopologyEventListener { - -public void handleTopologyEvent(final TopologyEvent event) { -// your code here -} - -} + @Component + @Service(value = { TopologyEventListener.class }) + public class MyTopologyEventListener implements TopologyEventListener { + + public void handleTopologyEvent(final TopologyEvent event) { + // your code here + } + + } ## Properties @@ -108,26 +111,26 @@ meant to be used to announce configuration information for accessing proper mess The following is an example of a `PropertyProvider` that provides `sample.value1` and `sample.value2` properties: -import org.apache.felix.scr.annotations.Component; -import org.apache.felix.scr.annotations.Service; -import org.apache.sling.discovery.PropertyProvider; - -@Component -@Service(value = { PropertyProvider.class }) -@Property(name = PropertyProvider.PROPERTY_PROPERTIES, -value = {"sample.value1", "sample.value2" }) -public class SamplePropertyProvider implements PropertyProvider { - -public String getProperty(final String name) { -if ("sample.value1".equals(name)) { -return "foo"; -} else if ("sample.value2".equals(name)) { -return "bar"; -} else { -return null; -} -} -} + import org.apache.felix.scr.annotations.Component; + import org.apache.felix.scr.annotations.Service; + import org.apache.sling.discovery.PropertyProvider; + + @Component + @Service(value = { PropertyProvider.class }) + @Property(name = PropertyProvider.PROPERTY_PROPERTIES, + value = {"sample.value1", "sample.value2" }) + public class SamplePropertyProvider implements PropertyProvider { + + public String getProperty(final String name) { + if ("sample.value1".equals(name)) { + return "foo"; + } else if ("sample.value2".equals(name)) { + return "bar"; + } else { + return null; + } + } + } ## Deployment and configuration @@ -137,10 +140,10 @@ might choose explicit configuration via a central service etc. ## discovery.impl: Resource-based, OOTB Implementation -The `discovery.impl` bundle is a resource-based, out of the box implementation of the `discovery.api` using standard Sling. +The `discovery.impl` bundle is a resource-based, out of the box implementation of the `discovery.api` using standard Sling. The discovery within a cluster is done by writing heartbeat information into the (common) repository (there's no other form -of communication within a cluster). The establishment of a +of communication within a cluster). The establishment of a clusterview is done by analyzing these heartbeats, initiating a voting within the cluster (such that each instance can agree that it sees the same number of instances) and by concluding the voting by promoting it as the new "established" view. @@ -151,7 +154,7 @@ The discovery of instances and clusters outside the local cluster requires expli Administrative note: All the information about the topology is stored at the following location in the repository: -/var/discovery/impl + /var/discovery/impl #### /var/discovery/impl/clusterInstances/<slingId> @@ -197,7 +200,7 @@ the following properties: This area is used for voting. Each instance can initiate a voting when it realizes that the live instances - denominated by those instances that have a not-yet-timed-out heartbeat property - does not match with the `establishedView`. -Once a voting gets a yes vote by all instances it is promoted (moved) under `establishedView` by the initiating instance. +Once a voting gets a yes vote by all instances it is promoted (moved) under `establishedView` by the initiating instance. Each establishedView was once a voting, thus the structure is the same as described above. #### /var/discovery/impl/previousView @@ -217,7 +220,7 @@ This is done by setting a corresponding `lastHeartbeat` property to the current To avoid having each instance make it's own, perhaps differing conclusions as to which instance/heartbeat is dead or not, there is an explicit, unanimous voting mechanism that agrees upon a list of alive instances. This list of alive -instances is called cluster view. +instances is called cluster view. * as soon as any instance notices a change in the list of active instances, it is free to calculate a new such list and start a voting in the cluster - each voting carries a unique votingId @@ -231,15 +234,15 @@ passed on in a TopologyEvent to all registered listeners. ### pseudo-network partitioning aka split-brain `discovery.impl` requires the, eventually consistent, underlying repository to propagate changes within reasonable time: -in less than the configured heartbeat timeout. If heartbeats for some reason are not becoming visible by peers in -the cluster within that time, `discovery.impl` will consider that peer instance as dead. At which point it will +in less than the configured heartbeat timeout. If heartbeats for some reason are not becoming visible by peers in +the cluster within that time, `discovery.impl` will consider that peer instance as dead. At which point it will first send a TOPOLOGY_CHANGING event to all listeners to make them aware that something is changing in the topology, and then start a new voting. Once the voting concludes a TOPOLOGY_CHANGED event will follow. -Given the voting is happening through the repository as well, one could imagine a situation where the repository delays +Given the voting is happening through the repository as well, one could imagine a situation where the repository delays can cause a topology to be "pseudo partitioned" into two or more parts, each one agreeing on a set of instances in that sub-cluster (one requirement for such a scenario being that the delays must be asymmetric, ie changes from a subset -of instances propagate slow, while the remaining changes propagate fast - ie. two different sets of delays in the cluster). +of instances propagate slow, while the remaining changes propagate fast - ie. two different sets of delays in the cluster). Such a situation would only last as long as the repository delays are large (larger than the heartbeat timeouts). Exact cases where the repository experiences large delays depend of course on the repository configuration and deployment details, known cases include for example long running queries, large set @@ -268,7 +271,7 @@ such that the delays are well under control and do not exceed the configured hea From a discovery API's point of view a cluster consists of all instances that are connected to the same repository. The above described built-in mechanism of storing a lastHeartbeat property into the (shared) repository, of voting on changes -and creating an explicit establishedView results in automatic discovery within a cluster. There is therefore +and creating an explicit establishedView results in automatic discovery within a cluster. There is therefore no further configuration needed for discovering instances in the same cluster. However, for discovering multiple clusters such an automatic discovery is not possible and the clusters need @@ -276,11 +279,11 @@ to be explicitly configured using (cross-cluster) topology connectors: A topology connector is a periodically issued HTTP PUT that announces the part of the topology known to the sending instance to the receiving instance and vica-verca the receiving instance announces its part of the -topology to the sender in the response of the very same HTTP PUT. This way whatever other clusters are connected +topology to the sender in the response of the very same HTTP PUT. This way whatever other clusters are connected to sender or receiver will be made known to each other. Such a 'topology announcement' will be valid either until the same sender sends the announcement again (which it does periodically) - or until it times out (configurable). -A topology connector is by definition always between clusters, never within the same cluster. Topology connectors -can be structured in an arbitrary way (chain, star, tree, etc) with the only important point to note here that +A topology connector is by definition always between clusters, never within the same cluster. Topology connectors +can be structured in an arbitrary way (chain, star, tree, etc) with the only important point to note here that since changes in the topology propagate through these topology connectors they have a certain delay (namely the configured heartbeatInterval per hop). @@ -295,47 +298,47 @@ A Felix WebConsole plugin at [/system/console/topology][2] provides a (read-only The following properties can be configured (at [/system/console/configMgr/org.apache.sling.discovery.impl.Config][1]): -* heartbeatInterval: the time in seconds between two heartbeats (both cluster-internal and for HTTP-connectors). Default -value is 15 seconds. - -* heartbeatTimeout: the time in seconds after which an instance is considered dead if no heartbeat was sent since. Default -value is 20 seconds. - -* topologyConnectorUrls: a list of connector URLs to which this instance should connect to. The list can contain multiple -instances of the same cluster (for fallback configurations). If the list is empty, no connector will be created. -The default relative URL is /libs/sling/topology/connector. Note that this URL is accessible without authentication - -to avoid having to configure administrative username/passwords in all instances. Instead, a whitelist approach is used -(see next item). - -* topologyConnectorWhitelist: As mentioned above, the path /libs/sling/topology/connector does not require authentication. -To assure that only trusted instances can connect to the topology, its hostname or IP address must be in a whitelist. -By default this whitelist only contains localhost and 127.0.0.1. - -* minEventDelay: To reduce the number of events sent during changes, there is a delay (in seconds) before the event is sent. -If additional changes happen during this delay, the change will be combined in one event. - -* leaderElectionRepositoryDescriptor: this is an advanced parameter. It denotes a repository descriptor that is evaluated -and taken into account for leader Election: the corresponding value of the descriptor is sorted by first. - -* hmacEnabled: If this is true, and sharedKey is set to a value on all Sling instances within the same topology, then messages are -validates using a signature of the content of the message based on the shared key. The signature and the digest of the content -appear as http headers. When hmac message validation is enabled, whitelisting is disabled. This use useful where the topology -messages are transported through multiple reverse proxy layers or the topology is dynamic. The Hmac algorithm in use is HmacSHA256. -The JVM is expected to have a provider implementing this algorithm (The Standard JDKs do). - -* sharedKey: If hmacEnabled is true, this must be set to a secret value, shared amongst all Sling instances that are members of the -same topology. - -* enableEncryption: If hmacEnabled is true, and sharedKey is set, setting this to true will encrypt the body of the message using 128 Bit -AES encryption. The encryption key is derived from the sharedKey using a 9 byte random salt, giving 2^^72 potential salt values. - -* hmacSharedKeyTTL: The key used for the signatures is derived from the shared key. Each derived key has a lifetime before the next key -is generated. This parameter sets the lifetime of each key in ms. The default is 4h. Messages sent using old keys will remain valid for -2x the TTL, after which time the message will be ignored. - - -[1]: http://localhost:8888/system/console/configMgr/org.apache.sling.discovery.impl.Config -[2]: http://localhost:8888/system/console/topology + * heartbeatInterval: the time in seconds between two heartbeats (both cluster-internal and for HTTP-connectors). Default + value is 15 seconds. + + * heartbeatTimeout: the time in seconds after which an instance is considered dead if no heartbeat was sent since. Default + value is 20 seconds. + + * topologyConnectorUrls: a list of connector URLs to which this instance should connect to. The list can contain multiple + instances of the same cluster (for fallback configurations). If the list is empty, no connector will be created. + The default relative URL is /libs/sling/topology/connector. Note that this URL is accessible without authentication - + to avoid having to configure administrative username/passwords in all instances. Instead, a whitelist approach is used + (see next item). + + * topologyConnectorWhitelist: As mentioned above, the path /libs/sling/topology/connector does not require authentication. + To assure that only trusted instances can connect to the topology, its hostname or IP address must be in a whitelist. + By default this whitelist only contains localhost and 127.0.0.1. + + * minEventDelay: To reduce the number of events sent during changes, there is a delay (in seconds) before the event is sent. + If additional changes happen during this delay, the change will be combined in one event. + + * leaderElectionRepositoryDescriptor: this is an advanced parameter. It denotes a repository descriptor that is evaluated + and taken into account for leader Election: the corresponding value of the descriptor is sorted by first. + + * hmacEnabled: If this is true, and sharedKey is set to a value on all Sling instances within the same topology, then messages are + validates using a signature of the content of the message based on the shared key. The signature and the digest of the content + appear as http headers. When hmac message validation is enabled, whitelisting is disabled. This use useful where the topology + messages are transported through multiple reverse proxy layers or the topology is dynamic. The Hmac algorithm in use is HmacSHA256. + The JVM is expected to have a provider implementing this algorithm (The Standard JDKs do). + + * sharedKey: If hmacEnabled is true, this must be set to a secret value, shared amongst all Sling instances that are members of the + same topology. + + * enableEncryption: If hmacEnabled is true, and sharedKey is set, setting this to true will encrypt the body of the message using 128 Bit + AES encryption. The encryption key is derived from the sharedKey using a 9 byte random salt, giving 2^^72 potential salt values. + + * hmacSharedKeyTTL: The key used for the signatures is derived from the shared key. Each derived key has a lifetime before the next key + is generated. This parameter sets the lifetime of each key in ms. The default is 4h. Messages sent using old keys will remain valid for + 2x the TTL, after which time the message will be ignored. + + + [1]: http://localhost:8888/system/console/configMgr/org.apache.sling.discovery.impl.Config + [2]: http://localhost:8888/system/console/topology ## discovery.oak: Oak-based, OOTB-implementation @@ -368,7 +371,7 @@ the current state of the cluster. It contains the following: * `inactive`: a list of nodes that are inactive * `me`: the id (number) of the local instance (which is always part of the active nodes) * `id`: the id (unique, persistent) of the cluster (which thus survives node/cluster restarts) -* `seq`: a sequence number that is incremented upon each change in this descriptor (to be able to identify a change even if +* `seq`: a sequence number that is incremented upon each change in this descriptor (to be able to identify a change even if the other values are unchanged) and shared amongst all instances in the cluster, ie all instances see the same sequence number. This number can thus be used by upper layers to identify this particular incarnation of clusterview. * `final`: when this flag is `false` it indicates that the sequence number has changed (as well as eg `active` and `inactive`), @@ -380,7 +383,7 @@ should wait until `final==true`, at which point they know oak has finished proce The `oak.discoverylite.clusterview` descriptor is exposed as a JCR repository descriptor and can be accessed like so: -getRepository().getDescriptor("oak.discoverylite.clusterview") + getRepository().getDescriptor("oak.discoverylite.clusterview") which will return the json-formatted clusterview as described above. @@ -391,7 +394,7 @@ It is merely an internal information exposed by oak and not standardized nor gua discovery.oak is a implementation of the discovery API that now makes use of this new discovery-lite descriptor in oak. It basically delegates the detection of the instances in the local cluster to discovery-lite. To do so, it periodically -reads this descriptor (which is designed to be read at a high-frequency without problems) and triggers `TopologyEvents` +reads this descriptor (which is designed to be read at a high-frequency without problems) and triggers `TopologyEvents` when this descriptor changes. The advantage of using discovery-lite (which uses oak leases) instead of writing heartbeats into the repository
http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/bundles/dynamic-includes.md ---------------------------------------------------------------------- diff --git a/content/documentation/bundles/dynamic-includes.md b/content/documentation/bundles/dynamic-includes.md index 54a4b77..9b9c25c 100644 --- a/content/documentation/bundles/dynamic-includes.md +++ b/content/documentation/bundles/dynamic-includes.md @@ -1,27 +1,30 @@ -title=Apache Sling Dynamic Include -type=page +title=TODO title for dynamic-includes.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Apache Sling Dynamic Include Notice: 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. + 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. Sling Dynamic Include (org.apache.sling.dynamic-include) ======================================================== For now the Sling Dynamic Include documentation can be found [in the Sling codebase](https://svn.apache.org/repos/asf/sling/trunk/contrib/extensions/sling-dynamic-include/README.md) -or +or [on our GitHub mirror](https://github.com/apache/sling/tree/trunk/contrib/extensions/sling-dynamic-include) if that's in sync. http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/bundles/file-installer-provider.md ---------------------------------------------------------------------- diff --git a/content/documentation/bundles/file-installer-provider.md b/content/documentation/bundles/file-installer-provider.md index 9332f83..ccc6127 100644 --- a/content/documentation/bundles/file-installer-provider.md +++ b/content/documentation/bundles/file-installer-provider.md @@ -1,15 +1,18 @@ -title=File Installer Provider -type=page +title=TODO title for file-installer-provider.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: File Installer Provider The file installer provider scans configured directories and provides the found artifacts (files) to the [OSGI installer](/documentation/bundles/osgi-installer.html). The functionality is very similar to Apache Felix FileInstall, with the major difference that this service implements just the task of scanning a file directory. All the management logic is implemented in the OSGi installer and support of various artifact types like bundles, configurations or custom formats is implemented by plugins for the OSGi installer. - + ## Setup - + The file installer can be configured with these framework (system) properties: - + |Property|Default|Description| |--|--|--| |`sling.fileinstall.dir`| |The name/path of the directories to watch. Several directories can be specified by using a comma separated list. Each directory might have arbitrarily many sub directories (even nested ones) which may contain the artifacts| @@ -26,14 +29,14 @@ Start levels are supported as well by creating a directory with the name of the ## Configurations Configurations are handled by the [Configuration Installer Factory](/documentation/bundles/configuration-installer-factory.html). The different formats are described there. - + ## Custom Artifacts Custom artifacts are handled by the OSGi installer depending on the installed plugins. Have a look at the OSGi installer and its plugins for more information. ## Runmode Support -The file installer supports run modes for installing artifacts (added with [SLING-4478](https://issues.apache.org/jira/browse/SLING-4478)). Within the scanned directory, a folder prefixed with "install." and followed by one or more run modes (separated by ".") will only be considered if all the respective run modes are active. For example artifacts below a folder named `install.a1.dev` are only taken into account if the run modes `a1` and `dev` are both active. +The file installer supports run modes for installing artifacts (added with [SLING-4478](https://issues.apache.org/jira/browse/SLING-4478)). Within the scanned directory, a folder prefixed with "install." and followed by one or more run modes (separated by ".") will only be considered if all the respective run modes are active. For example artifacts below a folder named `install.a1.dev` are only taken into account if the run modes `a1` and `dev` are both active. You can even combine start level and run mode support. Just pay attention that the run mode foldername must be set on a direct child folder of `sling.fileinstall.dir` while the start level must be set directly on the parent folder of the artifact you want to install. E.g. `<sling.fileinstall.dir>/install.a1.dev/3/mybundle.jar` will only be considered if both run modes `a1` and `dev` are set. If this is the case then the according artifact will be installed in start level 3. http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/bundles/internationalization-support-i18n.md ---------------------------------------------------------------------- diff --git a/content/documentation/bundles/internationalization-support-i18n.md b/content/documentation/bundles/internationalization-support-i18n.md index 49961ca..bbf4709 100644 --- a/content/documentation/bundles/internationalization-support-i18n.md +++ b/content/documentation/bundles/internationalization-support-i18n.md @@ -1,14 +1,17 @@ -title=Internationalization Support (i18n) -type=page +title=TODO title for internationalization-support-i18n.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Internationalization Support (i18n) Internationalization support in Sling consists of four methods in the `SlingHttpServletRequest` interface: -* `getLocale()` -- Returns the primary `Locale` for the current request. This method is inherited from the `javax.servlet.ServletRequest` interface. -* `getLocales()` -- Returns the `Locale` instances for the current request. This method is inherited from the `javax.servlet.ServletRequest` interface. -* `getResourceBundle(Locale)` -- Returns a `ResourceBundle` for the given `Locale`. This method is specific to Sling. -* `getResourceBundle(String, Locale)` -- Returns a `ResourceBundle` of a given base name for the given `Locale`. This method is specific to Sling. + * `getLocale()` -- Returns the primary `Locale` for the current request. This method is inherited from the `javax.servlet.ServletRequest` interface. + * `getLocales()` -- Returns the `Locale` instances for the current request. This method is inherited from the `javax.servlet.ServletRequest` interface. + * `getResourceBundle(Locale)` -- Returns a `ResourceBundle` for the given `Locale`. This method is specific to Sling. + * `getResourceBundle(String, Locale)` -- Returns a `ResourceBundle` of a given base name for the given `Locale`. This method is specific to Sling. These methods have a default implementation in the `org.apache.sling.core` bundle and an extended and extensible implementation in the `org.apache.sling.i18n` bundle. @@ -18,10 +21,10 @@ These methods have a default implementation in the `org.apache.sling.core` bundl The default implementation of the above mentioned four methods in the Sling Engine bundle is contained in the bundle-private class `org.apache.sling.engine.impl.SlingHttpServletRequestImpl` which is the primary implementation of the `SlingHttpServletRequest` interface: -* `getLocale()` -- Returns the `Locale` from the request object of the servlet container in which Sling is running. As per the Servlet API specification, this is either the primary Locale of the `Accept-Language` request header or the server default locale. -* `getLocales()` -- Returns the `Enumeration` from the request object of the servlet container in which Sling is running. As per the Servlet API specification, this is either based on the `Accept-Language` request header or just the server default locale. -* `getResourceBundle(Locale)` -- Returns a `ResourceBundle` whose `getString(String key)` method returns the `key` as the message and whose `getKeys()` method returns an empty `Enumeration`. -* `getResourceBundle(String, Locale)` -- Returns a `ResourceBundle` whose `getString(String key)` method returns the `key` as the message and whose `getKeys()` method returns an empty `Enumeration`. + * `getLocale()` -- Returns the `Locale` from the request object of the servlet container in which Sling is running. As per the Servlet API specification, this is either the primary Locale of the `Accept-Language` request header or the server default locale. + * `getLocales()` -- Returns the `Enumeration` from the request object of the servlet container in which Sling is running. As per the Servlet API specification, this is either based on the `Accept-Language` request header or just the server default locale. + * `getResourceBundle(Locale)` -- Returns a `ResourceBundle` whose `getString(String key)` method returns the `key` as the message and whose `getKeys()` method returns an empty `Enumeration`. + * `getResourceBundle(String, Locale)` -- Returns a `ResourceBundle` whose `getString(String key)` method returns the `key` as the message and whose `getKeys()` method returns an empty `Enumeration`. NOTE: Unlike the default implementations of the `ResourceBundle` abstract class in the Java Runtime -- `PropertyResourceBundle` and `ListResourceBundle` -- the `ResourceBundle` returned by the default implementation of the `getResourceBundle(Locale)` and `getResourceBundle(String, Locale)` always returns a string message for any key, which is the key itself. This prevents throwing `MissingResourceException`. @@ -32,9 +35,9 @@ NOTE: Unlike the default implementations of the `ResourceBundle` abstract class The `org.apache.sling.i18n` Bundle implements a request level `Filter` providing extensible implementations of the above mentioned three methods. Extensibility is attained by defining two service interfaces: -* `LocaleResolver` -- The `LocaleResolver` interface defines a method which may be implemented by a service outside of the sling.i18n bundle. If no such service is registered the default behaviour is as described above for the sling.core bundle. The service described by this interface is used to implement the `getLocale()` and `getLocales()` method. + * `LocaleResolver` -- The `LocaleResolver` interface defines a method which may be implemented by a service outside of the sling.i18n bundle. If no such service is registered the default behaviour is as described above for the sling.core bundle. The service described by this interface is used to implement the `getLocale()` and `getLocales()` method. -* `ResourceBundleProvider` -- The `ResourceBundleProvider` interface defines two methods to acquire a `ResourceBundle` for any `Locale` and an optional base name. This service interface is not intended to be implemented outside of the sling.i18n bundle: A JCR Repository based implementation is contained in the sling.i18n bundle. The `ResourceBundleProvider` service is not only used within the sling.i18n bundle to implement the `SlingHttpServletRequest.getResourceBundle(Locale)` and `SlingHttpServletRequest.getResourceBundle(String, Locale)` methods. The service may also be used by Sling applications to acquire `ResourceBundle` instances without having a request object by getting the service and calling its `getResourceBundle(Locale)` or `getResourceBundle(String, Locale)` method directly. + * `ResourceBundleProvider` -- The `ResourceBundleProvider` interface defines two methods to acquire a `ResourceBundle` for any `Locale` and an optional base name. This service interface is not intended to be implemented outside of the sling.i18n bundle: A JCR Repository based implementation is contained in the sling.i18n bundle. The `ResourceBundleProvider` service is not only used within the sling.i18n bundle to implement the `SlingHttpServletRequest.getResourceBundle(Locale)` and `SlingHttpServletRequest.getResourceBundle(String, Locale)` methods. The service may also be used by Sling applications to acquire `ResourceBundle` instances without having a request object by getting the service and calling its `getResourceBundle(Locale)` or `getResourceBundle(String, Locale)` method directly. @@ -50,8 +53,8 @@ Two different types of storage formats are supported for the individual dictiona The (direct) child nodes of the `mix:language` node must have the `jcr:primaryType` set to `sling:MessageEntry` and must contain two special properties naming the key string and the message: -* `sling:key` -- The `sling:key` property is a string property being the key for which the node contains the message(s). This property is optional. If it is not set the key is determined by the name of this `sling:messageEntry` resource. -* `sling:message` -- The `sling:message` property represents the resource for the key. + * `sling:key` -- The `sling:key` property is a string property being the key for which the node contains the message(s). This property is optional. If it is not set the key is determined by the name of this `sling:messageEntry` resource. + * `sling:message` -- The `sling:message` property represents the resource for the key. It is only required that the message nodes are located below `mix:language` nodes. Such structures may also be scattered in the repository to allow storing message resources next to where they are most likely used, such as request scripts. @@ -59,35 +62,35 @@ It is only required that the message nodes are located below `mix:language` node Content for dictionaries in this format might look like this: -/libs/languages -+-- English (nt:folder, mix:language) -| +-- jcr:language = en -| +-- m1 (sling:MessageEntry) -| | +-- sling:key = "msg001" -| | +-- sling:message = "This is a message" -| +-- m2 (sling:MessageEntry) -| +-- sling:key = "msg002" -| +-- sling:message = "Another message" -+-- Deutsch (nt:folder, mix:language) -+-- jcr:language = de -+-- m1 (sling:MessageEntry) -| +-- sling:key = "msg001" -| +-- sling:message = "Das ist ein Text" -+-- m2 (sling:MessageEntry) -+-- sling:key = "msg002" -+-- sling:message = "Ein anderer Text" - -/apps/myApp -+-- English (nt:folder, mix:language) -| +-- jcr:language = en -| +-- mx (sling:MessageEntry) -| +-- sling:key = "msgXXX" -| +-- sling:message = "An Application Text" -+-- Deutsch (nt:folder, mix:language) -+-- jcr:language = de -+-- mx (sling:MessageEntry) -+-- sling:key = "msgXXX" -+-- sling:message = "Ein Anwendungstext" + /libs/languages + +-- English (nt:folder, mix:language) + | +-- jcr:language = en + | +-- m1 (sling:MessageEntry) + | | +-- sling:key = "msg001" + | | +-- sling:message = "This is a message" + | +-- m2 (sling:MessageEntry) + | +-- sling:key = "msg002" + | +-- sling:message = "Another message" + +-- Deutsch (nt:folder, mix:language) + +-- jcr:language = de + +-- m1 (sling:MessageEntry) + | +-- sling:key = "msg001" + | +-- sling:message = "Das ist ein Text" + +-- m2 (sling:MessageEntry) + +-- sling:key = "msg002" + +-- sling:message = "Ein anderer Text" + + /apps/myApp + +-- English (nt:folder, mix:language) + | +-- jcr:language = en + | +-- mx (sling:MessageEntry) + | +-- sling:key = "msgXXX" + | +-- sling:message = "An Application Text" + +-- Deutsch (nt:folder, mix:language) + +-- jcr:language = de + +-- mx (sling:MessageEntry) + +-- sling:key = "msgXXX" + +-- sling:message = "Ein Anwendungstext" This content defines two languages *en* and *de* with three messages *msg001*, *msg002* and *msgXXX* each. The names of the respective resources have no significance (in case the `sling:key` is set). @@ -102,34 +105,34 @@ The parser will take any "key":"value" pair in the JSON file, including those in Content for this format might look like this: -/libs/languages -+-- english.json (nt:file, mix:language) -| +-- jcr:language = en -| +-- jcr:content (nt:resource) -| + jcr:data (containing the actual JSON file) -+-- deutsch.json (nt:file, mix:language) -+-- jcr:language = de -+-- jcr:content (nt:resource) -+ jcr:data (containing the actual JSON file) + /libs/languages + +-- english.json (nt:file, mix:language) + | +-- jcr:language = en + | +-- jcr:content (nt:resource) + | + jcr:data (containing the actual JSON file) + +-- deutsch.json (nt:file, mix:language) + +-- jcr:language = de + +-- jcr:content (nt:resource) + + jcr:data (containing the actual JSON file) #### JCR Node Types supporting the JCR Repository based `ResourceBundleProvider` The sling.i18n bundle asserts the following node types: -[mix:language] -mixin -- jcr:language (string) + [mix:language] + mixin + - jcr:language (string) The `mix:language` mixin node type allows setting the `jcr:language` property required by the `ResourceBundleProvider` implementation to identify the message `Locale`. -[sling:Message] -mixin -- sling:key (string) -- sling:message (undefined) - -[sling:MessageEntry] > nt:hierarchyNode, sling:Message + [sling:Message] + mixin + - sling:key (string) + - sling:message (undefined) + + [sling:MessageEntry] > nt:hierarchyNode, sling:Message The `sling:Message` and `sling:MessageEntry` are helper node types. The latter must be used to create the nodes for the `sling:MessageEntry` based format. @@ -151,9 +154,9 @@ The `sling:basename` property may be multi-valued, that is the messages of a `mi ### `ResourceBundle` hierarchies The dictionary entries for one `JcrResourceBundle` are always ordered like the resource resolver search paths, so usually -1. dictionary entries below `/apps` -2. dictionary entries below `/libs` -3. dictionary entries anywhere else (outside the search path) + 1. dictionary entries below `/apps` + 2. dictionary entries below `/libs` + 3. dictionary entries anywhere else (outside the search path) That means that the message for the same key in `/apps` overwrites the one in `/libs` (if both are for the same locale and base name). Within those categories the order is non-deterministic, so if there is more than one entry for the same key in `/apps/...` (for the same locale and base name), any of those entries may be used. http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/bundles/jcr-installer-provider.md ---------------------------------------------------------------------- diff --git a/content/documentation/bundles/jcr-installer-provider.md b/content/documentation/bundles/jcr-installer-provider.md index 73fc668..55877a2 100644 --- a/content/documentation/bundles/jcr-installer-provider.md +++ b/content/documentation/bundles/jcr-installer-provider.md @@ -1,7 +1,10 @@ -title=JCR Installer Provider -type=page +title=TODO title for jcr-installer-provider.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: JCR Installer Provider The JCR installer provider scans the JCR repository for artifacts and provides them to the [OSGI installer](/documentation/bundles/osgi-installer.html). @@ -9,7 +12,7 @@ The JCR installer provider scans the JCR repository for artifacts and provides t The JCR installer provider can be configured with weighted paths which are scanned. By default, the installer scans in */apps* and */libs* where artifacts found in */apps* get a higher priority. The installer does a deep scan and uses a regular expression to detect folders containing artifacts to be installed. By default, artifacts from within a folder named *install* are provided to the OSGi installer. -If such an install folder contains a binary artifact (e.g. a bundle or a config file as described in [Configuration Installer Factory](/documentation/bundles/configuration-installer-factory.html)) this is provided to the OSGi installer. +If such an install folder contains a binary artifact (e.g. a bundle or a config file as described in [Configuration Installer Factory](/documentation/bundles/configuration-installer-factory.html)) this is provided to the OSGi installer. In addition every node of type *sling:OsgiConfig* is provided as a configuration to the installer. This has the advantage of leveraging the JCR structure better than binary files, but has the known limitations outlined in [SLING-4183](https://issues.apache.org/jira/browse/SLING-4183) and [SLING-2477](https://issues.apache.org/jira/browse/SLING-2477), therefore it is recommended to stick to one of the binary formats described in [Configuration Installer Factory](/documentation/bundles/configuration-installer-factory.html). @@ -17,7 +20,7 @@ The JCR installer provider does not check or scan the artifacts itself, the dete ### Runmode Support -The JCR installer supports run modes for installing artifacts. By default folders named *install* are checked for artifacts. If Apache Sling is started with one (or more run modes), all folders named *install.[RUNMODE]* are scanned as well. To be precise, the folder name can be followed by any number of run modes separated by comma. For example, if started with run modes *dev*, *a1*, and *public*, folders like *install.dev*, *install.a1*, *install.public* are searched as well as *install.dev.a1*, or *install.a1.dev*. +The JCR installer supports run modes for installing artifacts. By default folders named *install* are checked for artifacts. If Apache Sling is started with one (or more run modes), all folders named *install.\[RUNMODE\]* are scanned as well. To be precise, the folder name can be followed by any number of run modes separated by comma. For example, if started with run modes *dev*, *a1*, and *public*, folders like *install.dev*, *install.a1*, *install.public* are searched as well as *install.dev.a1*, or *install.a1.dev*. Artifacts from folders with a run mode get a higher priority. For example by default, an *install* folder underneath */libs* gets the priority *50*. For each run mode in the folder name, this priority is increased by *1*, so *install.dev* has *51* and *install.a1.dev* is *52*. @@ -31,7 +34,7 @@ Write back can be turned off by configuration. ### Start Level Support -If the parent folder of a bundle has a name which is a number, this is used as the start level (when installing the bundle for the first time, compare with [SLING-2011](https://issues.apache.org/jira/browse/SLING-2011)). So e.g. a bundle in the path `/libs/sling/install/15/somebundle.jar` is having the start level **15**. +If the parent folder of a bundle has a name which is a number, this is used as the start level (when installing the bundle for the first time, compare with [SLING-2011](https://issues.apache.org/jira/browse/SLING-2011)). So e.g. a bundle in the path `/libs/sling/install/15/somebundle.jar` is having the start level **15**. # Example Here's a quick walkthrough of the JCR installer functionality. @@ -53,14 +56,15 @@ We use `curl` to create content, to make it easy to reproduce the example by cop By default, JCRInstall picks up bundles found in folders named *install* under `/libs` and `/apps`, so we start by creating such a folder: -curl -X MKCOL http://admin:admin@localhost:8888/apps/jcrtest -curl -X MKCOL http://admin:admin@localhost:8888/apps/jcrtest/install + curl -X MKCOL http://admin:admin@localhost:8888/apps/jcrtest + curl -X MKCOL http://admin:admin@localhost:8888/apps/jcrtest/install And we copy the bundle to install in that folder (a backslash in command lines means *continued on next line*): -curl -T desktop_awt_all-2.0.0.jar http://admin:admin@localhost:8888/apps/jcrtest/install/desktop_awt_all-2.0.0.jar + curl -T desktop_awt_all-2.0.0.jar \ + http://admin:admin@localhost:8888/apps/jcrtest/install/desktop_awt_all-2.0.0.jar That's it. After 2-3 seconds, the bundle should be picked up by JCRInstall, installed and started. If this works you'll see a small *Knopflerfish Desktop* window on your desktop, and Sling's OSGi console can of course be used to check the details. @@ -68,7 +72,8 @@ That's it. After 2-3 seconds, the bundle should be picked up by JCRInstall, inst Removing the bundle from the repository will cause it to be uninstalled, so: -curl -X DELETE http://admin:admin@localhost:8888/apps/jcrtest/install/desktop_awt_all-2.0.0.jar + curl -X DELETE \ + http://admin:admin@localhost:8888/apps/jcrtest/install/desktop_awt_all-2.0.0.jar Should cause the *Knopflerfish Desktop* window to disappear as the bundle is uninstalled. @@ -80,30 +85,34 @@ JCRInstall installs OSGi configurations from nodes having the *sling:OsgiConfig* Let's try this feature by creating a configuration with two properties: -curl -F "jcr:primaryType=sling:OsgiConfig" -F foo=bar -F works=yes http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid + curl \ + -F "jcr:primaryType=sling:OsgiConfig" \ + -F foo=bar -F works=yes \ + http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid And verify the contents of our config node: -curl http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid.json + curl \ + http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid.json Which should display something like -{"foo":"bar", -"jcr:created":"Wed Aug 26 2009 17:06:40GMT+0200", -"jcr:primaryType":"sling:OsgiConfig","works":"yes"} + {"foo":"bar", + "jcr:created":"Wed Aug 26 2009 17:06:40GMT+0200", + "jcr:primaryType":"sling:OsgiConfig","works":"yes"} At this point, JCRInstall should have picked up our new config and installed it. The logs would confirm that, but we can also use the OSGi console's config status page (http://localhost:8888/system/console/config) to check it. That page should now contain: -PID=some.config.pid -BundleLocation=Unbound -_jcr_config_path=jcrinstall:/apps/jcrtest/install/some.config.pid -foo=bars -service.pid=some.config.pid -works=yes + PID=some.config.pid + BundleLocation=Unbound + _jcr_config_path=jcrinstall:/apps/jcrtest/install/some.config.pid + foo=bars + service.pid=some.config.pid + works=yes Indicating that the configuration has been installed. @@ -111,25 +120,28 @@ Indicating that the configuration has been installed. Let's try modifying the configuration parameters: -curl -F works=updated -F even=more http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid + curl \ + -F works=updated -F even=more \ + http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid And check the changes in the console page: -PID=some.config.pid -BundleLocation=Unbound -_jcr_config_path=jcrinstall:/apps/jcrtest/install/some.config.pid -even=more -foo=bars -service.pid=some.config.pid -works=updated + PID=some.config.pid + BundleLocation=Unbound + _jcr_config_path=jcrinstall:/apps/jcrtest/install/some.config.pid + even=more + foo=bars + service.pid=some.config.pid + works=updated We can now delete the configuration node: -curl -X DELETE http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid + curl -X DELETE \ + http://admin:admin@localhost:8888/apps/jcrtest/install/some.config.pid And verify that the corresponding configuration is gone in the console page (after 1-2 seconds, like for all other JCRInstall operations). http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/bundles/log-tracers.md ---------------------------------------------------------------------- diff --git a/content/documentation/bundles/log-tracers.md b/content/documentation/bundles/log-tracers.md index b6630a5..e021b2a 100644 --- a/content/documentation/bundles/log-tracers.md +++ b/content/documentation/bundles/log-tracers.md @@ -1,9 +1,12 @@ -title=Log Tracer -type=page +title=TODO title for log-tracers.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Log Tracer -[Log Tracer][SLING-4739] provides support for enabling the logs for specific category at specific +[Log Tracer][SLING-4739] provides support for enabling the logs for specific category at specific level and only for specific request. It provides a very fine level of control via config provided as part of HTTP request around how the logging should be performed for given category. @@ -14,49 +17,55 @@ Using Tracer one can enable log for that request which is required to be probed. For e.g. determining what nodes are written for a given POST request can be simply done by including an extra request parameters. -curl -D - -u admin:admin -d "./jcr:content/jcr:title=Summer Collection" -d ":name=summer-collection" -d "./jcr:primaryType=sling:Folder" -d "./jcr:content/jcr:primaryType=nt:unstructured" -d "tracers=oak-writes" http://localhost:4502/content/dam/ + curl -D - -u admin:admin \ + -d "./jcr:content/jcr:title=Summer Collection" \ + -d ":name=summer-collection" \ + -d "./jcr:primaryType=sling:Folder" \ + -d "./jcr:content/jcr:primaryType=nt:unstructured" \ + -d "tracers=oak-writes" \ + http://localhost:4502/content/dam/ ## Configuration  -**Note that by default Tracer would not be enabled and you would need to save the OSGi config to +**Note that by default Tracer would not be enabled and you would need to save the OSGi config to get it activated** Tracer support two ways to enable logging. ### Tracer Sets -Tracer sets are collection of predefined logging categories matching specific area of an application. +Tracer sets are collection of predefined logging categories matching specific area of an application. These can for now be configured as part of OSGi config -oak-query : org.apache.jackrabbit.oak.query.QueryEngineImpl;level=debug -auth : org.apache.sling.auth;level=trace,org.apache.jackrabbit.oak.security + oak-query : org.apache.jackrabbit.oak.query.QueryEngineImpl;level=debug + auth : org.apache.sling.auth;level=trace,org.apache.jackrabbit.oak.security The config is of following format -< set name > : <tracer config> + < set name > : <tracer config> Where the config is of following format -tracerConfig := loggerConfig ( ',' loggerConfig) * -loggerConfig := loggerName (; attributes)* -attributes := attributeName '=' attributeValue + tracerConfig := loggerConfig ( ',' loggerConfig) * + loggerConfig := loggerName (; attributes)* + attributes := attributeName '=' attributeValue Currently following attributes are support * `level` - Either of TRACE, DEBUG, INFO, WARN, ERROR * `caller` - Used to dump stacktrace of caller. It can have following value (_since 1.0.0_, [SLING-5505][SLING-5505]) -* `true` - Complete call stack for that logger would be included -* `<depth>` - Call stack upto depth (integer) would be included e.g. caller=5 -* `caller-exclude-filter` - (optional) - '|' separated package prefixes which should not be -included in the output. e.g. _org.apache.jackrabbit.oak.query.QueryImpl;caller=28;caller-exclude-filter="org.eclipse|org.felix"_ -this would exclude eclipse and felix packages from the resulting stack + * `true` - Complete call stack for that logger would be included + * `<depth>` - Call stack upto depth (integer) would be included e.g. caller=5 +* `caller-exclude-filter` - (optional) - '|' separated package prefixes which should not be + included in the output. e.g. _org.apache.jackrabbit.oak.query.QueryImpl;caller=28;caller-exclude-filter="org.eclipse|org.felix"_ + this would exclude eclipse and felix packages from the resulting stack ### Performance Impact -Tracer makes use of [Logback TuboFilter][1] to intercept the logging calls and only enable them for -those which are enabled via tracer config for the request. The filter is only registered for the +Tracer makes use of [Logback TuboFilter][1] to intercept the logging calls and only enable them for +those which are enabled via tracer config for the request. The filter is only registered for the duration of that request hence would avoid adding the cost for normal run. You can also disable the Tracer completely via OSGi config. @@ -67,30 +76,30 @@ The logs captured are logged at two places ### RequestProgressTracker -Sling provides support for recording recent requests which can be accessed via [Recent Requests -Plugin][2]. It would list down the list of recent request and then on clicking them you can see the +Sling provides support for recording recent requests which can be accessed via [Recent Requests +Plugin][2]. It would list down the list of recent request and then on clicking them you can see the logs showed on the UI. -The logging there is done via [RequestProgressTracker][3] ([intro][4]). By default recent request -plugin gets overflown as it captures request even for css, js files. To avoid that you can modify +The logging there is done via [RequestProgressTracker][3] ([intro][4]). By default recent request +plugin gets overflown as it captures request even for css, js files. To avoid that you can modify the config as part of _Sling Main Servlet_ config  -Using a regex like ```^.*.(?!jpg$|png$|js$|css$|woff$)[^.]+$``` would avoid noise +Using a regex like ```^.*\.(?!jpg$|png$|js$|css$|woff$)[^.]+$``` would avoid noise With that you can see log entries like below at http://localhost:8080/system/console/requests?index=xxx -132 (2015-05-11 17:39:55) LOG [JCR] Query SELECT * FROM [granite:InboxItem] AS s where status='ACTIVE' ORDER BY s.startTime DESC -134 (2015-05-11 17:39:55) TIMER_END{53,/libs/cq/gui/components/endor/badge/badge.jsp#18} -... -1316 (2015-05-11 17:39:56) LOG JCR Query Count 3 -1320 (2015-05-11 17:39:56) TIMER_END{1320,Request Processing} Request Processing + 132 (2015-05-11 17:39:55) LOG [JCR] Query SELECT * FROM [granite:InboxItem] AS s where status='ACTIVE' ORDER BY s.startTime DESC + 134 (2015-05-11 17:39:55) TIMER_END{53,/libs/cq/gui/components/endor/badge/badge.jsp#18} + ... + 1316 (2015-05-11 17:39:56) LOG JCR Query Count 3 + 1320 (2015-05-11 17:39:56) TIMER_END{1320,Request Processing} Request Processing ### Server Logs -Further the logs also go to normal server side logs. By default they would go to the error.log. If -you have routed the logs of specific categories to different files then normal Logback logging rules +Further the logs also go to normal server side logs. By default they would go to the error.log. If +you have routed the logs of specific categories to different files then normal Logback logging rules would apply ## Usage @@ -107,27 +116,33 @@ Param names * `tracers` - Tracer set names * `tracerConfig` - Tracer config like org.apache.sling.auth;level=trace` -curl -u admin:admin http://localhost:4802/projects.html?tracerConfig=org.apache.sling + curl -u admin:admin http://localhost:4802/projects.html?tracerConfig=org.apache.sling Above request would turn on debug level logging (default level for tracer) for `org.apache.sling` category. -curl -D - -u admin:admin -d "./jcr:content/jcr:title=Summer Collection" -d ":name=summer-collection" -d "./jcr:primaryType=sling:Folder" -d "./jcr:content/jcr:primaryType=nt:unstructured" -d "tracers=oak-writes" http://localhost:4502/content/dam/ - -Above request would create a folder in Assets and for that we have enabled the `oak-writes` tracer. This would result in following output - -2015-05-11 17:30:42,840 INFO admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] c.a.acs.acs-aem-tools-bundle - Service [4858] ServiceEvent REGISTERED -2015-05-11 17:30:42,846 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] Adding node [/content/dam/summer-collection] -2015-05-11 17:30:42,849 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] setPrimaryType -2015-05-11 17:30:42,849 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] Adding node [/content/dam/summer-collection/jcr:content] -2015-05-11 17:30:42,849 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] Setting property [/content/dam/summer-collection/jcr:content/jcr:title] -2015-05-11 17:30:42,850 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] setPrimaryType -2015-05-11 17:30:42,850 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] setPrimaryType -2015-05-11 17:30:42,856 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] save + curl -D - -u admin:admin \ + -d "./jcr:content/jcr:title=Summer Collection" \ + -d ":name=summer-collection" \ + -d "./jcr:primaryType=sling:Folder" \ + -d "./jcr:content/jcr:primaryType=nt:unstructured" \ + -d "tracers=oak-writes" \ + http://localhost:4502/content/dam/ + +Above request would create a folder in Assets and for that we have enabled the `oak-writes` tracer. This would result in following output + + 2015-05-11 17:30:42,840 INFO admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] c.a.acs.acs-aem-tools-bundle - Service [4858] ServiceEvent REGISTERED + 2015-05-11 17:30:42,846 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] Adding node [/content/dam/summer-collection] + 2015-05-11 17:30:42,849 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] setPrimaryType + 2015-05-11 17:30:42,849 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] Adding node [/content/dam/summer-collection/jcr:content] + 2015-05-11 17:30:42,849 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] Setting property [/content/dam/summer-collection/jcr:content/jcr:title] + 2015-05-11 17:30:42,850 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] setPrimaryType + 2015-05-11 17:30:42,850 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] setPrimaryType + 2015-05-11 17:30:42,856 TRACE admin [127.0.0.1 [1431345642836] POST /content/dam/ HTTP/1.1] o.a.j.o.jcr.operations.writes session-12895- [session-12895] save ### Request Headers -Some request like initial authentication processing does not involve Sling MainServlet and hence for -those request logging cannot be done to RequestProgressTracker. Instead we can just get logs enabled +Some request like initial authentication processing does not involve Sling MainServlet and hence for +those request logging cannot be done to RequestProgressTracker. Instead we can just get logs enabled and route them to normal logging on server side. For that you need to use HTTP header * `Sling-Tracers` - Set of tracer set names @@ -135,16 +150,20 @@ and route them to normal logging on server side. For that you need to use HTTP h So to enable authentication related logging following request can be sent -curl -D - -d "j_username=admin" -d "j_password=admin" -d "j_validate=true" -H "Sling-Tracer-Config : org.apache.sling.auth;level=trace,org.apache.jackrabbit.oak.security;level=trace" http://localhost:8080/libs/content/login.html/j_security_check + curl -D - -d "j_username=admin" \ + -d "j_password=admin" \ + -d "j_validate=true" \ + -H "Sling-Tracer-Config : org.apache.sling.auth;level=trace,org.apache.jackrabbit.oak.security;level=trace" \ + http://localhost:8080/libs/content/login.html/j_security_check This would result in following server side logs -2015-05-11 17:34:56,531 INFO NA [qtp1395423247-193] c.a.acs.acs-aem-tools-bundle - Service [4859] ServiceEvent REGISTERED -2015-05-11 17:34:56,532 DEBUG NA [qtp1395423247-193] o.a.s.a.c.i.SlingAuthenticator - doHandleSecurity: Trying to get a session for null -2015-05-11 17:34:56,532 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.LoginContextProviderImpl - Found pre-authenticated subject: No further login actions required. -2015-05-11 17:34:56,532 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.LoginContextProviderImpl - Found pre-authenticated subject: No further login actions required. -2015-05-11 17:34:56,548 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.u.LoginModuleImpl - Adding Credentials to shared state. -2015-05-11 17:34:56,548 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.u.LoginModuleImpl - Adding login name to shared state. + 2015-05-11 17:34:56,531 INFO NA [qtp1395423247-193] c.a.acs.acs-aem-tools-bundle - Service [4859] ServiceEvent REGISTERED + 2015-05-11 17:34:56,532 DEBUG NA [qtp1395423247-193] o.a.s.a.c.i.SlingAuthenticator - doHandleSecurity: Trying to get a session for null + 2015-05-11 17:34:56,532 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.LoginContextProviderImpl - Found pre-authenticated subject: No further login actions required. + 2015-05-11 17:34:56,532 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.LoginContextProviderImpl - Found pre-authenticated subject: No further login actions required. + 2015-05-11 17:34:56,548 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.u.LoginModuleImpl - Adding Credentials to shared state. + 2015-05-11 17:34:56,548 DEBUG NA [qtp1395423247-193] o.a.j.o.s.a.u.LoginModuleImpl - Adding login name to shared state. ## Tracer Recording @@ -158,56 +177,65 @@ Recording features works as explained below 1. Client sends an HTTP request with header `Sling-Tracer-Record`â set to `true` -curl -D - -u admin:admin -H "Sling-Tracer-Record : true" -d "./jcr:content/jcr:title=Summer Collection" -d ":name=summer-collection" -d "./jcr:primaryType=sling:Folder" -d "./jcr:content/jcr:primaryType=nt:unstructured" -d "tracers=oak-writes" http://localhost:4802/content/dam/ - -2. Server includes a request id as part of `Sling-Tracer-Request-Id` response headers - -HTTP/1.1 201 Created -Date: Wed, 27 Jan 2016 07:30:22 GMT -Sling-Tracer-Request-Id: 9b5b01f6-f269-47c3-a889-2dc8d4d7938f -X-Content-Type-Options: nosniff -X-Frame-Options: SAMEORIGIN -Location: /content/dam/summer-collection -Content-Type: text/html; charset=UTF-8 -Transfer-Encoding: chunked - -3. The logs in json format can then be fetched from server at `/system/console/tracer` like -http://localhost:8080/system/console/tracer/9b5b01f6-f269-47c3-a889-2dc8d4d7938f.json. - -curl -s -D - -H "Sling-Tracer-Record : true" -H "Sling-Tracers : oak-query" -H "Sling-Tracer-Config : org.apache.jackrabbit.oak.query" -u admin:admin http://localhost:4512/assets.html/content/dam -o /dev/null - -Below is a json output for GET request - -:::javascript -{ -"method": "GET", -"time": 15140, -"timestamp": 1461574009024, -"requestProgressLogs": [ -"0 TIMER_START{Request Processing}", -"0 COMMENT timer_end format is {<elapsed msec>,<timer name>} <optional message>", -... -], -"queries": [{ -"query": "/jcr:root/etc/workflow/instances//element(*,app:Workflow)[@status='RUNNING'] order by @startTime descending", -"plan": "[app:Workflow] as [a] /* property status = RUNNING where ([a].[status] = 'RUNNING') and (isdescendantnode([a], [/etc/workflow/instances])) */", -"caller": "com.example.WorkflowManager.getWorkflowInstances(WorkflowManager.java:902)" -} -], -"logs": [{ -"timestamp": 1461574022401, -"level": "DEBUG", -"logger": "org.apache.jackrabbit.oak.query.QueryEngineImpl", -"message": "Parsing xpath statement: /jcr:root/etc/workflow/instances//element(*,cq:Workflow)[@status='RUNNING'] order by @startTime descending", -"params": [ -"xpath", -"/jcr:root/etc/workflow/instances//element(*,cq:Workflow)[@status='RUNNING'] order by @startTime descending" -] -} -... -] -} - + curl -D - -u admin:admin \ + -H "Sling-Tracer-Record : true" \ + -d "./jcr:content/jcr:title=Summer Collection" \ + -d ":name=summer-collection" \ + -d "./jcr:primaryType=sling:Folder" \ + -d "./jcr:content/jcr:primaryType=nt:unstructured" \ + -d "tracers=oak-writes" \ + http://localhost:4802/content/dam/ + +2. Server includes a request id as part of `Sling-Tracer-Request-Id` response headers + + HTTP/1.1 201 Created + Date: Wed, 27 Jan 2016 07:30:22 GMT + Sling-Tracer-Request-Id: 9b5b01f6-f269-47c3-a889-2dc8d4d7938f + X-Content-Type-Options: nosniff + X-Frame-Options: SAMEORIGIN + Location: /content/dam/summer-collection + Content-Type: text/html; charset=UTF-8 + Transfer-Encoding: chunked + +3. The logs in json format can then be fetched from server at `/system/console/tracer` like + http://localhost:8080/system/console/tracer/9b5b01f6-f269-47c3-a889-2dc8d4d7938f.json. + + curl -s -D - -H "Sling-Tracer-Record : true" -H "Sling-Tracers : oak-query" \ + -H "Sling-Tracer-Config : org.apache.jackrabbit.oak.query" \ + -u admin:admin http://localhost:4512/assets.html/content/dam -o /dev/null + + Below is a json output for GET request + + :::javascript + { + "method": "GET", + "time": 15140, + "timestamp": 1461574009024, + "requestProgressLogs": [ + "0 TIMER_START{Request Processing}", + "0 COMMENT timer_end format is {<elapsed msec>,<timer name>} <optional message>", + ... + ], + "queries": [{ + "query": "/jcr:root/etc/workflow/instances//element(*,app:Workflow)[@status='RUNNING'] order by @startTime descending", + "plan": "[app:Workflow] as [a] /* property status = RUNNING where ([a].[status] = 'RUNNING') and (isdescendantnode([a], [/etc/workflow/instances])) */", + "caller": "com.example.WorkflowManager.getWorkflowInstances(WorkflowManager.java:902)" + } + ], + "logs": [{ + "timestamp": 1461574022401, + "level": "DEBUG", + "logger": "org.apache.jackrabbit.oak.query.QueryEngineImpl", + "message": "Parsing xpath statement: /jcr:root/etc/workflow/instances//element(*,cq:Workflow)[@status='RUNNING'] order by @startTime descending", + "params": [ + "xpath", + "/jcr:root/etc/workflow/instances//element(*,cq:Workflow)[@status='RUNNING'] order by @startTime descending" + ] + } + ... + ] + } + JSON output consist of following sections 1. `method` - Request method @@ -215,7 +243,7 @@ JSON output consist of following sections 3. `timestamp` - Request start time 4. `requestProgressLogs` - Sling Request Progress Tracker log for the given request 5. `queries` - List of queries fired along with details around `query`, `plan` and `caller` i.e. from where -the query is invoked + the query is invoked 6. `logs` - List of log entries captured (as enabled by tracer config) for current request The recordings are held in memory for 15 mins (per default setting) and can be seen listed at http://localhost:8080/system/console/tracer. Look into the OSGi config for more config options @@ -225,12 +253,12 @@ around this. Download the bundle from [here][5] or use following Maven dependency -::xml -<dependency> -<groupId>org.apache.sling</groupId> -<artifactId>org.apache.sling.tracer</artifactId> -<version>1.0.0</version> -</dependency> + ::xml + <dependency> + <groupId>org.apache.sling</groupId> + <artifactId>org.apache.sling.tracer</artifactId> + <version>1.0.0</version> + </dependency> [1]: http://logback.qos.ch/manual/filters.html#TurboFilter http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/bundles/managing-permissions-jackrabbit-accessmanager.md ---------------------------------------------------------------------- diff --git a/content/documentation/bundles/managing-permissions-jackrabbit-accessmanager.md b/content/documentation/bundles/managing-permissions-jackrabbit-accessmanager.md index 99b4c24..add943e 100644 --- a/content/documentation/bundles/managing-permissions-jackrabbit-accessmanager.md +++ b/content/documentation/bundles/managing-permissions-jackrabbit-accessmanager.md @@ -1,7 +1,10 @@ -title=Managing permissions (jackrabbit.accessmanager) -type=page +title=TODO title for managing-permissions-jackrabbit-accessmanager.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Managing permissions (jackrabbit.accessmanager) The `jackrabbit-accessmanager` bundle delivers a REST interface to manipulate users permissions in the JCR. After installing the `jackrabbit-accessmanager` bundle the REST services are exposed under the path of the node where you will manipulate the permissions for a user with a specific selector like `modifyAce`, `acl` and `deleteAce`. @@ -19,38 +22,38 @@ The `jackrabbit-accessmanager` bundle delivers a REST interface to manipulate us | jcr:removeNode | the privilege to remove a node | | jcr:write | an aggregate privilege that contains: jcr:modifyProperties jcr:addChildNodes jcr:removeNode jcr:removeChildNodes | | jcr:modifyAccessControl | the privilege to modify the access control policies of a node | -| jcr:lockManagement | the privilege to lock and unlock a node | -| jcr:versionManagement | the privilege to perform versioning operations on a node | -| jcr:nodeTypeManagement | the privilege to add and remove mixin node types and change the primary node type of a node | -| jcr:retentionManagement | the privilege to perform retention management operations on a node | -| jcr:lifecycleManagement | the privilege to perform lifecycle operations on a node | +| jcr:lockManagement | the privilege to lock and unlock a node | +| jcr:versionManagement | the privilege to perform versioning operations on a node | +| jcr:nodeTypeManagement | the privilege to add and remove mixin node types and change the primary node type of a node | +| jcr:retentionManagement | the privilege to perform retention management operations on a node | +| jcr:lifecycleManagement | the privilege to perform lifecycle operations on a node | | jcr:all | an aggregate privilege that contains all predefined privileges | ## Add or modify permissions To modify the permissions for a node POST a request to `/<path-to-the-node>.modifyAce.<html or json>`. The following parameters are available: - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + * *numeric* - Place the target ACE at the specified numeric index. | @@ -59,44 +62,44 @@ Responses: | 500 | Failure, HTML (or JSON) explains failure. | Example with curl: -curl -FprincipalId=myuser -Fprivilege@jcr:read=granted http://localhost:8080/test/node.modifyAce.html + curl -FprincipalId=myuser -Fprivilege@jcr:read=granted http://localhost:8080/test/node.modifyAce.html ## Delete permissions To delete permissions for a node POST a request to `/<path-to-the-node>.deleteAce.<html or json>`. The following parameters are available: - - - - + + + + Responses: | 200 | Success | | 500 | Failure, HTML (or JSON) explains failure. | Example with curl: -curl -F:applyTo=myuser http://localhost:8080/test/node.deleteAce.html + curl -F:applyTo=myuser http://localhost:8080/test/node.deleteAce.html ## Get permissions ### Bound Permissions -To get the permissions bound to a particular node in a json format for a node send a GET request to `/<path-to-the-node>.acl.json`. +To get the permissions bound to a particular node in a json format for a node send a GET request to `/<path-to-the-node>.acl.json`. Example: -http://localhost:8080/test/node.acl.json + http://localhost:8080/test/node.acl.json ### Effective Permissions -To get the permissions which are effective for a particular node in a json format for a node send a GET request to `/<path-to-the-node>.eacl.json`. +To get the permissions which are effective for a particular node in a json format for a node send a GET request to `/<path-to-the-node>.eacl.json`. Example: -http://localhost:8080/test/node.eacl.json + http://localhost:8080/test/node.eacl.json <div class="note">
