http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/development/jsr-305.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/jsr-305.md b/content/documentation/development/jsr-305.md index 8080d91..3fb8fc3 100644 --- a/content/documentation/development/jsr-305.md +++ b/content/documentation/development/jsr-305.md @@ -1,7 +1,10 @@ -title=Leveraging JSR-305 null annotations to prevent NullPointerExceptions -type=page +title=TODO title for jsr-305.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Leveraging JSR-305 null annotations to prevent NullPointerExceptions [TOC] @@ -21,13 +24,13 @@ Annotations which support setting the default null semantics of return values an The annotations have a retention policy of `runtime`, therefore bundles using these automatically have a `Import-Package` header listing `javax.annotation`. That package is by default exported by the system bundle (as this package is also part of the [JRE](https://docs.oracle.com/javase/7/docs/api/javax/annotation/package-summary.html)). To be able to resolve the bundle through this exported package from the system bundle you should use the `com.google.code.findbugs:jsr305` artifact in version 3.0.0 as that exports the package `javax.annotation` in no specific version. Newer versions use version directives which automatically restrict the version range for the generated `Import-Package` header to `[3,4)` [which usually cannot be resolved at run time](https://github.com/amaembo/jsr-305/issues/31). # Use With Eclipse -Eclipse since Juno supports [null analysis based on any annotations](http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Freference%2Fpreferences%2Fjava%2Fcompiler%2Fref-preferences-errors-warnings.htm&anchor=null_analysis). Those need to be enabled in +Eclipse since Juno supports [null analysis based on any annotations](http://help.eclipse.org/juno/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Freference%2Fpreferences%2Fjava%2Fcompiler%2Fref-preferences-errors-warnings.htm&anchor=null_analysis). Those need to be enabled in *Preferences->Java->Compiler->Errors/Warnings* via **Enable annoation-based null analysis**. Also the annotations need to be configured. For Sling/JSR 305 those are * `javax.annotation.CheckForNull` as **'Nullable' annotation** (primary annotation) * `javax.annotation.Nonnull` as **'NonNull' annotation** (primary annotation) - +  Unfortunately Eclipse cannot infer information about fields which are for sure either null or not null (reasoning is available in [https://wiki.eclipse.org/JDT_Core/Null_Analysis/Options#Risks_of_flow_analysis_for_fields](https://wiki.eclipse.org/JDT_Core/Null_Analysis/Options#Risks_of_flow_analysis_for_fields) and [Eclipse Bug 247564](https://bugs.eclipse.org/bugs/show_bug.cgi?id=247564)). This also affecs constants (static final fields) or enums which are known to be non null, but still Eclipse will emit a warning like *The expression of type 'String' needs unchecked conversion to conform to '@Nonnull String'*. The only known workaround is to disable the **"Unchecked conversion from non-annotated type to @NonNull type"** or to annotate also the field with `@Nonnull`. @@ -41,58 +44,58 @@ Since Eclipse 4.5 (Mars) **external annotations** are supported as well (i.e. an ## Leveraging Eclipse JDT Compiler (recommended) -You can use Eclipse JDT also in Maven (with null analysis enabled) for the regular compilation. That way it will give out the same warnings/errors as Eclipse and will also consider external annotations. +You can use Eclipse JDT also in Maven (with null analysis enabled) for the regular compilation. That way it will give out the same warnings/errors as Eclipse and will also consider external annotations. JDT in its most recent version is provided by the `tycho-compiler-plugin` which can be hooked up with the `maven-compiler-plugin`. The full list of options for JDT is described in [here](http://help.eclipse.org/neon/index.jsp?topic=%2Forg.eclipse.jdt.doc.user%2Ftasks%2Ftask-using_batch_compiler.htm). This method was presented by Michael Vorburger in his presentation [The end of the world as we know it](https://www.slideshare.net/mikervorburger/the-end-of-the-world-as-we-know-it-aka-your-last-nullpointerexception-1b-bugs/14). -::xml -<plugin> -<artifactId>maven-compiler-plugin</artifactId> -<version>3.5.1</version> -<configuration> -<source>1.8</source> -<target>1.8</target> -<showWarnings>true</showWarnings> -<compilerId>jdt</compilerId> -<compilerArguments> -<!-- just take the full Maven classpath as external annotations --> -<annotationpath>CLASSPATH</annotationpath> -</compilerArguments> -<!-- maintain the org.eclipse.jdt.core.prefs properties to options listed on -http://help.eclipse.org/neon/index.jsp?topic=/org.eclipse.jdt.doc.user/tasks/task-using_batch_compiler.htm --> -<compilerArgument>-err:nullAnnot,null,-missingNullDefault</compilerArgument> -</configuration> -<dependencies> -<dependency> -<groupId>org.eclipse.tycho</groupId> -<artifactId>tycho-compiler-jdt</artifactId> -<version>1.0.0</version> -</dependency> -</dependencies> -</plugin> + ::xml + <plugin> + <artifactId>maven-compiler-plugin</artifactId> + <version>3.5.1</version> + <configuration> + <source>1.8</source> + <target>1.8</target> + <showWarnings>true</showWarnings> + <compilerId>jdt</compilerId> + <compilerArguments> + <!-- just take the full Maven classpath as external annotations --> + <annotationpath>CLASSPATH</annotationpath> + </compilerArguments> + <!-- maintain the org.eclipse.jdt.core.prefs properties to options listed on + http://help.eclipse.org/neon/index.jsp?topic=/org.eclipse.jdt.doc.user/tasks/task-using_batch_compiler.htm --> + <compilerArgument>-err:nullAnnot,null,-missingNullDefault</compilerArgument> + </configuration> + <dependencies> + <dependency> + <groupId>org.eclipse.tycho</groupId> + <artifactId>tycho-compiler-jdt</artifactId> + <version>1.0.0</version> + </dependency> + </dependencies> + </plugin> ## Leveraging FindBugs You can also let Maven automatically run FindBugs to execute those checks via the **findbugs-maven-plugin**. For that just add the following plugin to your `pom.xml` -::xml -<plugin> -<groupId>org.codehaus.mojo</groupId> -<artifactId>findbugs-maven-plugin</artifactId> -<version>3.0.0</version> -<configuration> -<visitors>InconsistentAnnotations,NoteUnconditionalParamDerefs,FindNullDeref,FindNullDerefsInvolvingNonShortCircuitEvaluation</visitors> -</configuration> -<executions> -<execution> -<id>run-findbugs-fornullchecks</id> -<goals> -<goal>check</goal> -</goals> -</execution> -</executions> -</plugin> - + ::xml + <plugin> + <groupId>org.codehaus.mojo</groupId> + <artifactId>findbugs-maven-plugin</artifactId> + <version>3.0.0</version> + <configuration> + <visitors>InconsistentAnnotations,NoteUnconditionalParamDerefs,FindNullDeref,FindNullDerefsInvolvingNonShortCircuitEvaluation</visitors> + </configuration> + <executions> + <execution> + <id>run-findbugs-fornullchecks</id> + <goals> + <goal>check</goal> + </goals> + </execution> + </executions> + </plugin> + The results are often very imprecise ([MFINDBUGS-208](http://jira.codehaus.org/browse/MFINDBUGS-208)), especially when it comes to line numbers, therefore it is best to start the Findbugs GUI in case of errors found by this plugin via `mvn findbugs:gui`. @@ -107,7 +110,7 @@ FindBugs evaluates the JSR-305 annotations by default. You can restrict the rule A complete list of visitors class names in Findbugs can be found in the [sourcecode](https://code.google.com/p/findbugs/source/browse/#git%2Ffindbugs%2Fsrc%2Fjava%2Fedu%2Fumd%2Fcs%2Ffindbugs%2Fdetect%253Fstate%253Dclosed). The according [bug patterns](http://findbugs.sourceforge.net/bugDescriptions.html) have an identifier (in parenthesis) for which you can search in the according Java classes, in case you want to extend the checks. -Findbugs is also integrated in [SonarQube](http://docs.sonarqube.org/display/SONAR/Findbugs+Plugin) but for SonarQube you should now rather use the native Java plugin +Findbugs is also integrated in [SonarQube](http://docs.sonarqube.org/display/SONAR/Findbugs+Plugin) but for SonarQube you should now rather use the native Java plugin (look at [Use with SonarQube](#use-with-sonarqube)). # Use with SonarQube
http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/development/logging.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/logging.md b/content/documentation/development/logging.md index 53bcd91..3c554f0 100644 --- a/content/documentation/development/logging.md +++ b/content/documentation/development/logging.md @@ -1,7 +1,10 @@ -title=Logging -type=page +title=TODO title for logging.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Logging <div class="note"> This document is for the new (November 2013) 4.x release of the Sling Commons Log components. Refer to @@ -18,19 +21,19 @@ following features: * Implements the OSGi Log Service Specification and registers the `LogService` and `LogReader` services * Exports three commonly used logging APIs: -* [Simple Logging Facade for Java (SLF4J)](http://www.slf4j.org) -* [Apache Commons Logging](http://jakarta.apache.org/commons/logging) -* [log4j](http://logging.apache.org/log4j/index.html) -* [java.util.logging](http://download.oracle.com/javase/6/docs/api/java/util/logging/package-summary.html) + * [Simple Logging Facade for Java (SLF4J)](http://www.slf4j.org) + * [Apache Commons Logging](http://jakarta.apache.org/commons/logging) + * [log4j](http://logging.apache.org/log4j/index.html) + * [java.util.logging](http://download.oracle.com/javase/6/docs/api/java/util/logging/package-summary.html) * Configures logging through Logback which is integrated with the OSGi environment * Allows logging to be configured both via editing Logback xml or via OSGi Configurations ### v5.0.0 release -With Sling Log 5.0.0. release the webconsole support has been moved to a +With Sling Log 5.0.0. release the webconsole support has been moved to a different bundle named Sling Commons Log WebConsole (org.apache.sling.commons.log.webconsole:1.0.0) -Also with this release Logback 1.1.7 version is embedded and thus it requires +Also with this release Logback 1.1.7 version is embedded and thus it requires slf4j-api:1.7.15. See [SLING-6144][SLING-6144] for details ## WebConsole Plugin @@ -63,8 +66,8 @@ It supports following parameters * `name` - Appender name like _/logs/error.log_ * `tail` - Number of lines to include in dump. -1 to include whole file * `grep` - Filter the log lines based on `grep` value which can be -* Simple string phrase - In this case search is done in case insensitive way via String.contains -* regex - In this case the search would be done via regex pattern matching + * Simple string phrase - In this case search is done in case insensitive way via String.contains + * regex - In this case the search would be done via regex pattern matching ## Initial Configuration @@ -77,7 +80,7 @@ The `org.apache.sling.commons.log` bundle gets its initial configuration from th | `org.apache.sling.commons.log.file` | undefined | Sets the log file to which log messages are written. If this property is empty or missing, log messages are written to `System.out`. | | `org.apache.sling.commons.log.file.number` | 5 | The number of rotated files to keep. | | `org.apache.sling.commons.log.file.size` | '.'yyyy-MM-dd | Defines how the log file is rotated (by schedule or by size) and when to rotate. See the section *Log File Rotation* below for full details on log file rotation. | -| `org.apache.sling.commons.log.pattern` | {0,date,dd.MM.yyyy HH:mm:ss.SSS} *{4}* [{2}]({{ refs.-2.path }}) {3} {5} | The `MessageFormat` pattern to use for formatting log messages with the root logger. | +| `org.apache.sling.commons.log.pattern` | \{0,date,dd.MM.yyyy HH:mm:ss.SSS\} \*\{4\}\* \[\{2\}\]({{ refs.-2.path }}) \{3\} \{5\} | The `MessageFormat` pattern to use for formatting log messages with the root logger. | | `org.apache.sling.commons.log.julenabled` | n/a | Enables the `java.util.logging` support. | | `org.apache.sling.commons.log.configurationFile` | n/a | Path for the Logback config file which would be used to configure logging. If the path is not absolute then it would be resolved against Sling Home | | `org.apache.sling.commons.log.packagingDataEnabled` | true | Boolean property to control packaging data support of Logback. See [Packaging Data][11] section of Logback for more details | @@ -104,8 +107,8 @@ The following properties may be set: |--|--|--|--| | `org.apache.sling.commons.log.level` | `String` | `INFO` | Sets the logging level of the loggers. This may be any of the defined logging levels `DEBUG`, `INFO`, `WARN`, `ERROR` and `FATAL`. | | `org.apache.sling.commons.log.file` | `String` | undefined | Sets the log file to which log messages are written. If this property is empty or missing, log messages are written to `System.out`. This property should refer to the file name of a configured Log Writer (see below). If no Log Writer is configured with the same file name an implicit Log Writer configuration with default configuration is created. | -| `org.apache.sling.commons.log.pattern` | `String` | {0,date,dd.MM.yyyy HH:mm:ss.SSS} *{4}* [{2}]({{ refs.-2.path }}) {3} {5} | The `java.util.MessageFormat` pattern to use for formatting log messages with the root logger. This is a `java.util.MessageFormat` pattern supporting up to six arguments: {0} The timestamp of type `java.util.Date`, {1} the log marker, {2} the name of the current thread, {3} the name of the logger, {4} the log level and {5} the actual log message. If the log call includes a Throwable, the stacktrace is just appended to the message regardless of the pattern. | -| `org.apache.sling.commons.log.names` | `String[]` | -- | A list of logger names to which this configuration applies. | +| `org.apache.sling.commons.log.pattern` | `String` | \{0,date,dd.MM.yyyy HH:mm:ss.SSS\} \*\{4\}\* \[\{2\}\]({{ refs.-2.path }}) \{3\} \{5\} | The `java.util.MessageFormat` pattern to use for formatting log messages with the root logger. This is a `java.util.MessageFormat` pattern supporting up to six arguments: \{0\} The timestamp of type `java.util.Date`, \{1\} the log marker, \{2\} the name of the current thread, \{3\} the name of the logger, \{4\} the log level and \{5\} the actual log message. If the log call includes a Throwable, the stacktrace is just appended to the message regardless of the pattern. | +| `org.apache.sling.commons.log.names` | `String\[\]` | -- | A list of logger names to which this configuration applies. | | `org.apache.sling.commons.log.additiv` | `Boolean` | false | If set to false then logs from these loggers would not be sent to any appender attached higher in the hierarchy | @@ -197,22 +200,22 @@ The following sections provide more details. [Logback TurboFilters][3] operate globally and are invoked for every Logback call. To register an OSGi `TurboFilter`, just to register an service that implements the `ch.qos.logback.classic.turbo.TurboFilter` interface. -:::java -import import ch.qos.logback.classic.turbo.MatchingFilter; + :::java + import import ch.qos.logback.classic.turbo.MatchingFilter; -SimpleTurboFilter stf = new SimpleTurboFilter(); -ServiceRegistration sr = bundleContext.registerService(TurboFilter.class.getName(), stf, null); + SimpleTurboFilter stf = new SimpleTurboFilter(); + ServiceRegistration sr = bundleContext.registerService(TurboFilter.class.getName(), stf, null); -private static class SimpleTurboFilter extends MatchingFilter { -@Override -public FilterReply decide(Marker marker, Logger logger, Level level, String format, -Object[] params, Throwable t) { -if(logger.getName().equals("turbofilter.foo.bar")){ -return FilterReply.DENY; -} -return FilterReply.NEUTRAL; -} -} + private static class SimpleTurboFilter extends MatchingFilter { + @Override + public FilterReply decide(Marker marker, Logger logger, Level level, String format, + Object[] params, Throwable t) { + if(logger.getName().equals("turbofilter.foo.bar")){ + return FilterReply.DENY; + } + return FilterReply.NEUTRAL; + } + } As these filters are invoked for every call they must execute quickly. @@ -223,24 +226,24 @@ be passed to the appender. When registering a filter the bundle needs to configu `appenders` which refers to list of appender names to which the Filter must be attached -:::java -import ch.qos.logback.core.filter.Filter; + :::java + import ch.qos.logback.core.filter.Filter; -SimpleFilter stf = new SimpleFilter(); -Dictionary<String, Object> props = new Hashtable<String, Object>(); -props.put("appenders", "TestAppender"); -ServiceRegistration sr = bundleContext.registerService(Filter.class.getName(), stf, props); + SimpleFilter stf = new SimpleFilter(); + Dictionary<String, Object> props = new Hashtable<String, Object>(); + props.put("appenders", "TestAppender"); + ServiceRegistration sr = bundleContext.registerService(Filter.class.getName(), stf, props); -private static class SimpleFilter extends Filter<ILoggingEvent> { + private static class SimpleFilter extends Filter<ILoggingEvent> { -@Override -public FilterReply decide(ILoggingEvent event) { -if(event.getLoggerName().equals("filter.foo.bar")){ -return FilterReply.DENY; -} -return FilterReply.NEUTRAL; -} -} + @Override + public FilterReply decide(ILoggingEvent event) { + if(event.getLoggerName().equals("filter.foo.bar")){ + return FilterReply.DENY; + } + return FilterReply.NEUTRAL; + } + } If the `appenders` value is set to `*` then the filter would be registered with all the appenders (`Since 4.0.4`) @@ -250,21 +253,21 @@ If the `appenders` value is set to `*` then the filter would be registered with just register a service that implements the `ch.qos.logback.core.Appender` interface. Such a service must have a `loggers` service property, which refers to list of logger names to which the Appender must be attached. -:::java -Dictionary<String,Object> props = new Hashtable<String, Object>(); + :::java + Dictionary<String,Object> props = new Hashtable<String, Object>(); -String[] loggers = { -"foo.bar:DEBUG", -"foo.bar.zoo:INFO", -}; + String[] loggers = { + "foo.bar:DEBUG", + "foo.bar.zoo:INFO", + }; -props.put("loggers",loggers); -sr = bundleContext.registerService(Appender.class.getName(),this,props); + props.put("loggers",loggers); + sr = bundleContext.registerService(Appender.class.getName(),this,props); ### Logback Config Fragment Support Logback supports including parts of a configuration file from another file (See [File Inclusion][4]). This module -extends that support by allowing other bundles to provide config fragments. There are two ways to achieve that, +extends that support by allowing other bundles to provide config fragments. There are two ways to achieve that, described below. #### Logback config fragments as String objects @@ -273,48 +276,48 @@ If you have the config as string then you can register that String instance as a set to true. The Sling Logback Extension monitors such objects and passes them to logback. -:::java -Properties props = new Properties(); -props.setProperty("logbackConfig","true"); + :::java + Properties props = new Properties(); + props.setProperty("logbackConfig","true"); -String config = "<included>n" + -" <appender name="FOOFILE" class="ch.qos.logback.core.FileAppender">n" + -" <file>${sling.home}/logs/foo.log</file>n" + -" <encoder>n" + -" <pattern>%d %-5level %logger{35} - %msg %n</pattern>n" + -" </encoder>n" + -" </appender>n" + -"n" + -" <logger name="foo.bar.include" level="INFO">n" + -" <appender-ref ref="FOOFILE" />n" + -" </logger>n" + -"n" + -"</included>"; + String config = "<included>\n" + + " <appender name=\"FOOFILE\" class=\"ch.qos.logback.core.FileAppender\">\n" + + " <file>${sling.home}/logs/foo.log</file>\n" + + " <encoder>\n" + + " <pattern>%d %-5level %logger{35} - %msg %n</pattern>\n" + + " </encoder>\n" + + " </appender>\n" + + "\n" + + " <logger name=\"foo.bar.include\" level=\"INFO\">\n" + + " <appender-ref ref=\"FOOFILE\" />\n" + + " </logger>\n" + + "\n" + + "</included>"; -registration = context.registerService(String.class.getName(),config,props); + registration = context.registerService(String.class.getName(),config,props); If the config needs to be updated just re-register the service so that changes are picked up. #### Logback config fragments as ConfigProvider instances -Another way to provide config fragments is with services that implement the +Another way to provide config fragments is with services that implement the `org.apache.sling.commons.log.logback.ConfigProvider` interface. -:::java -@Component -@Service -public class ConfigProviderExample implements ConfigProvider { -public InputSource getConfigSource() { -return new InputSource(getClass().getClassLoader().getResourceAsStream("foo-config.xml")); -} -} + :::java + @Component + @Service + public class ConfigProviderExample implements ConfigProvider { + public InputSource getConfigSource() { + return new InputSource(getClass().getClassLoader().getResourceAsStream("foo-config.xml")); + } + } -If the config changes then sending an OSGi event with the `org/apache/sling/commons/log/RESET` topic +If the config changes then sending an OSGi event with the `org/apache/sling/commons/log/RESET` topic resets the Logback runtime. -:::java -eventAdmin.sendEvent(new Event("org/apache/sling/commons/log/RESET",new Properties())); + :::java + eventAdmin.sendEvent(new Event("org/apache/sling/commons/log/RESET",new Properties())); ### External Config File @@ -322,16 +325,16 @@ Logback can be configured with an external file. The file name can be specified 1. OSGi config - Look for a config with name `Apache Sling Logging Configuration` and specify the config file path. 2. OSGi Framework Properties - Logback support also looks for a file named according to the OSGi framwork `org.apache.sling.commons.log.configurationFile` property. - + If you are providing an external config file then to support OSGi integration you need to add following action entry: -:::xml -<newRule pattern="*/configuration/osgi" -actionClass="org.apache.sling.commons.log.logback.OsgiAction"/> -<newRule pattern="*/configuration/appender-ref-osgi" -actionClass="org.apache.sling.commons.log.logback.OsgiAppenderRefAction"/> -<osgi/> + :::xml + <newRule pattern="*/configuration/osgi" + actionClass="org.apache.sling.commons.log.logback.OsgiAction"/> + <newRule pattern="*/configuration/appender-ref-osgi" + actionClass="org.apache.sling.commons.log.logback.OsgiAppenderRefAction"/> + <osgi/> The `osgi` element enables the OSGi integration support @@ -343,8 +346,8 @@ This allows for routing logging messages from JUL to the Logbback appenders. 1. Set the `org.apache.sling.commons.log.julenabled` framework property to true. -If `org.apache.sling.commons.log.julenabled` is found to be true then [LevelChangePropagator][8] would be -registered automatically with Logback +If `org.apache.sling.commons.log.julenabled` is found to be true then [LevelChangePropagator][8] would be +registered automatically with Logback ### <a name="config-override"></a>Configuring OSGi appenders in the Logback Config @@ -354,70 +357,70 @@ from within the Logback config file. OSGi config based appenders are named based For example, for the following OSGi config -org.apache.sling.commons.log.file="logs/error.log" -org.apache.sling.commons.log.level="INFO" -org.apache.sling.commons.log.file.size="'.'yyyy-MM-dd" -org.apache.sling.commons.log.file.number=I"7" -org.apache.sling.commons.log.pattern="{0,date,dd.MM.yyyy HH:mm:ss.SSS} *{4}* [{2}] {3} {5}" + org.apache.sling.commons.log.file="logs/error.log" + org.apache.sling.commons.log.level="INFO" + org.apache.sling.commons.log.file.size="'.'yyyy-MM-dd" + org.apache.sling.commons.log.file.number=I"7" + org.apache.sling.commons.log.pattern="{0,date,dd.MM.yyyy HH:mm:ss.SSS} *{4}* [{2}] {3} {5}" The Logback appender would be named `logs/error.log`. To extend/override the config in a Logback config create an appender with the name `logs/error.log`: -:::xml -<appender name="/logs/error.log" class="ch.qos.logback.core.FileAppender"> -<file>${sling.home}/logs/error.log</file> -<encoder> -<pattern>%d %-5level %X{sling.userId:-NA} [%thread] %logger{30} %marker- %msg %n</pattern> -<immediateFlush>true</immediateFlush> -</encoder> -</appender> + :::xml + <appender name="/logs/error.log" class="ch.qos.logback.core.FileAppender"> + <file>${sling.home}/logs/error.log</file> + <encoder> + <pattern>%d %-5level %X{sling.userId:-NA} [%thread] %logger{30} %marker- %msg %n</pattern> + <immediateFlush>true</immediateFlush> + </encoder> + </appender> -In this case the logging module creates an appender based on the Logback config instead of the OSGi config. +In this case the logging module creates an appender based on the Logback config instead of the OSGi config. This can be used to move the application from OSGi based configs to Logback based configs. ## Using Slf4j API 1.7 -With Slf4j API 1.7 onwards its possible to use logger methods with varargs i.e. log n arguments without +With Slf4j API 1.7 onwards its possible to use logger methods with varargs i.e. log n arguments without constructing an object array e.g. `log.info("This is a test {} , {}, {}, {}",1,2,3,4)`. Without var args -you need to construct an object array `log.info("This is a test {} , {}, {}, {}",new Object[] {1,2,3,4})`. +you need to construct an object array `log.info("This is a test {} , {}, {}, {}",new Object[] {1,2,3,4})`. To make use of this API and still be able to use your bundle on Sling systems which package older version of the API jar, follow the below steps. (See [SLING-3243][SLING-3243]) for more details. 1. Update the api version in the pom: -:::xml -<dependencies> -<dependency> -<groupId>org.slf4j</groupId> -<artifactId>slf4j-api</artifactId> -<version>1.7.5</version> -<scope>provided</scope> -</dependency> -... -</dependency> - -2. Add an `Import-Package` instruction with a custom version range: - -:::xml -<build> -<plugins> -<plugin> -<groupId>org.apache.felix</groupId> -<artifactId>maven-bundle-plugin</artifactId> -<extensions>true</extensions> -<configuration> -<instructions> -... -<Import-Package> -org.slf4j;version="[1.5,2)", -* -</Import-Package> -</instructions> -</configuration> -</plugin> -... -</plugins> -</build> + :::xml + <dependencies> + <dependency> + <groupId>org.slf4j</groupId> + <artifactId>slf4j-api</artifactId> + <version>1.7.5</version> + <scope>provided</scope> + </dependency> + ... + </dependency> + +2. Add an `Import-Package` instruction with a custom version range: + + :::xml + <build> + <plugins> + <plugin> + <groupId>org.apache.felix</groupId> + <artifactId>maven-bundle-plugin</artifactId> + <extensions>true</extensions> + <configuration> + <instructions> + ... + <Import-Package> + org.slf4j;version="[1.5,2)", + * + </Import-Package> + </instructions> + </configuration> + </plugin> + ... + </plugins> + </build> The Slf4j API bundle 1.7.x is binary compatible with 1.6.x. @@ -426,7 +429,7 @@ can still be deployed on older systems which provide only the 1.6.4 version of t ## Log Tracer -Log Tracer provides support for enabling the logs for specific category at specific +Log Tracer 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. @@ -435,7 +438,7 @@ Refer to [Log Tracer Doc](/documentation/bundles/log-tracers.html) for more deta ## Slf4j MDC Sling MDC Inserting Filter exposes various request details as part of [MDC][11]. - + Currently it exposes following variables: 1. `req.remoteHost` - Request remote host @@ -447,8 +450,8 @@ Currently it exposes following variables: 7. `sling.userId` - UserID associated with the request. Obtained from ResourceResolver 8. `jcr.sessionId` - Session ID of the JCR Session associated with current request. -The filter also allow configuration to extract data from request cookie, header and parameters. -Look for configuration with name 'Apache Sling Logging MDC Inserting Filter' for details on +The filter also allow configuration to extract data from request cookie, header and parameters. +Look for configuration with name 'Apache Sling Logging MDC Inserting Filter' for details on specifying header, cookie, param names.  @@ -456,62 +459,62 @@ specifying header, cookie, param names. <a name="mdc-pattern"> ### Including MDC in Log Message -To include the MDC value in log message you MUST use the [Logback pattern][15] based on Logback -and not the old MessageFormat based pattern. +To include the MDC value in log message you MUST use the [Logback pattern][15] based on Logback +and not the old MessageFormat based pattern. -%d{dd.MM.yyyy HH:mm:ss.SSS} *%p* [%X{req.remoteHost}] [%t] %c %msg%n + %d{dd.MM.yyyy HH:mm:ss.SSS} *%p* [%X{req.remoteHost}] [%t] %c %msg%n ### Installation Download the bundle from [here][12] or use following Maven dependency -::xml -<dependency> -<groupId>org.apache.sling</groupId> -<artifactId>org.apache.sling.extensions.slf4j.mdc</artifactId> -<version>1.0.0</version> -</dependency> - + ::xml + <dependency> + <groupId>org.apache.sling</groupId> + <artifactId>org.apache.sling.extensions.slf4j.mdc</artifactId> + <version>1.0.0</version> + </dependency> + ## Logback Groovy Fragment -This fragment is required to make use of Groovy based event evaluation support +This fragment is required to make use of Groovy based event evaluation support provided by Logback. This enables programatic filtering of the log messages and is useful to get desired logs without flooding the system. For example Oak -logs the JCR operations being performed via a particular session. if this lo is +logs the JCR operations being performed via a particular session. if this lo is enabled it would flood the log with messages from all the active session. However -if you need logging only from session created in a particular thread then that +if you need logging only from session created in a particular thread then that can be done in following way -::xml -<?xml version="1.0" encoding="UTF-8"?> -<configuration scan="true" scanPeriod="1 second"> -<jmxConfigurator/> -<newRule pattern="*/configuration/osgi" actionClass="org.apache.sling.commons.log.logback.OsgiAction"/> -<newRule pattern="*/configuration/appender-ref-osgi" actionClass="org.apache.sling.commons.log.logback.OsgiAppenderRefAction"/> -<osgi/> - -<appender name="OAK" class="ch.qos.logback.core.FileAppender"> -<filter class="ch.qos.logback.core.filter.EvaluatorFilter"> -<evaluator class="ch.qos.logback.classic.boolex.GEventEvaluator"> -<expression><![CDATA[ -return e.getThreadName().contains("JobHandler"); -]]></expression> -</evaluator> -<OnMismatch>DENY</OnMismatch> -<OnMatch>ACCEPT</OnMatch> -</filter> -<file>${sling.home}/logs/oak.log</file> -<encoder> -<pattern>%d %-5level [%thread] %marker- %msg %n</pattern> -<immediateFlush>true</immediateFlush> -</encoder> -</appender> - -<logger name="org.apache.jackrabbit.oak.jcr.operations" level="DEBUG" additivity="false"> -<appender-ref ref="OAK"/> -</logger> -</configuration> - + ::xml + <?xml version="1.0" encoding="UTF-8"?> + <configuration scan="true" scanPeriod="1 second"> + <jmxConfigurator/> + <newRule pattern="*/configuration/osgi" actionClass="org.apache.sling.commons.log.logback.OsgiAction"/> + <newRule pattern="*/configuration/appender-ref-osgi" actionClass="org.apache.sling.commons.log.logback.OsgiAppenderRefAction"/> + <osgi/> + + <appender name="OAK" class="ch.qos.logback.core.FileAppender"> + <filter class="ch.qos.logback.core.filter.EvaluatorFilter"> + <evaluator class="ch.qos.logback.classic.boolex.GEventEvaluator"> + <expression><![CDATA[ + return e.getThreadName().contains("JobHandler"); + ]]></expression> + </evaluator> + <OnMismatch>DENY</OnMismatch> + <OnMatch>ACCEPT</OnMatch> + </filter> + <file>${sling.home}/logs/oak.log</file> + <encoder> + <pattern>%d %-5level [%thread] %marker- %msg %n</pattern> + <immediateFlush>true</immediateFlush> + </encoder> + </appender> + + <logger name="org.apache.jackrabbit.oak.jcr.operations" level="DEBUG" additivity="false"> + <appender-ref ref="OAK"/> + </logger> + </configuration> + Logback exposes a variable `e` which is of type [ILoggingEvent][13]. It provides access to current logging event. Above logback config would route all log messages from `org.apache.jackrabbit.oak.jcr.operations` category to `${sling.home}/logs/oak.log`. Further only those log messages would be logged @@ -522,23 +525,23 @@ be customised. Currently the bundle is not released and has to be build from [here][14] -::xml -<dependency> -<groupId>org.apache.sling</groupId> -<artifactId>org.apache.sling.extensions.logback-groovy-fragment</artifactId> -<version>1.0.0-SNAPSHOT</version> -</dependency> + ::xml + <dependency> + <groupId>org.apache.sling</groupId> + <artifactId>org.apache.sling.extensions.logback-groovy-fragment</artifactId> + <version>1.0.0-SNAPSHOT</version> + </dependency> ## FAQ ##### Q. Can Sling Commons Log bundle be used in non Sling environments -This bundle does not depend on any other Sling bundle and can be easily used in any OSGi framework. +This bundle does not depend on any other Sling bundle and can be easily used in any OSGi framework. To get complete log support working you need to deploy following bundles * Slf4j-Api - org.slf4j:slf4j-api * Jcl over Slf4j - org.slf4j:jcl-over-slf4j -* Log4j over Slf4j - org.slf4j:log4j-over-slf4j +* Log4j over Slf4j - org.slf4j:log4j-over-slf4j * Sling Log Service - org.apache.sling:org.apache.sling.commons.logservice:1.0.2 * Sling Commons Log - org.apache.sling:org.apache.sling.commons.log:4.0.0 or above * Sling Log WebConsole - org.apache.sling.commons.log.webconsole:1.0.0 or above @@ -547,8 +550,8 @@ To get complete log support working you need to deploy following bundles You need to specify the location of logback.xml via `org.apache.sling.commons.log.configurationFile` -java -jar org.apache.sling.launchpad-XXX-standalone.jar -Dorg.apache.sling.commons.log.configurationFile=/path/to/logback - + java -jar org.apache.sling.launchpad-XXX-standalone.jar -Dorg.apache.sling.commons.log.configurationFile=/path/to/logback + [1]: http://logback.qos.ch/manual/filters.html [2]: http://logback.qos.ch/manual/appenders.html http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/development/maven-archetypes.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/maven-archetypes.md b/content/documentation/development/maven-archetypes.md index 81346ad..b11f34a 100644 --- a/content/documentation/development/maven-archetypes.md +++ b/content/documentation/development/maven-archetypes.md @@ -1,8 +1,11 @@ -title=Maven Archetypes -type=page +title=TODO title for maven-archetypes.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ translation_pending: true +Title: Maven Archetypes Sling includes four Maven archetypes to quick start development. See [http://maven.apache.org/archetype/maven-archetype-plugin/](http://maven.apache.org/archetype/maven-archetype-plugin/) for general information on using Maven archetypes. The Maven groupId for all Sling archetypes is `org.apache.sling`. http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/development/maven-launchpad-plugin.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/maven-launchpad-plugin.md b/content/documentation/development/maven-launchpad-plugin.md index 59b09a6..51ef494 100644 --- a/content/documentation/development/maven-launchpad-plugin.md +++ b/content/documentation/development/maven-launchpad-plugin.md @@ -1,8 +1,11 @@ -title=Maven Launchpad Plugin -type=page +title=TODO title for maven-launchpad-plugin.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ translation_pending: true +Title: Maven Launchpad Plugin <div class="note"> This page is out of sync with the latest maven-launchpad-plugin features and settings. For now, @@ -11,24 +14,24 @@ refer to the source code and the launchpad/builder and launchpad/testing modules The Maven Launchpad Plugin provides goals which facilitate the creation of OSGi applications. It supports the following runtime scenarios: -* A WAR file suitable for running in a JavaEE servlet container. -* A standalone Java application, with HTTP support from the Felix HttpService implementation -* Inside Apache Karaf + * A WAR file suitable for running in a JavaEE servlet container. + * A standalone Java application, with HTTP support from the Felix HttpService implementation + * Inside Apache Karaf In addition, the Maven Launchpad Plugin supports the publishing of an application descriptor, in the form of a *bundle list*, as a Maven artifact. This descriptor can then be used by downstream application builders as the basis for other applications. In Sling, this is embodied by two Maven projects: -* [org.apache.sling.launchpad](http://svn.apache.org/repos/asf/sling/trunk/launchpad/builder) - produces an application descriptor. -* [org.apache.sling.launchpad.testing](http://svn.apache.org/repos/asf/sling/trunk/launchpad/testing/) - uses the application descriptor from `org.apache.sling.launchpad` and adds two bundles. + * [org.apache.sling.launchpad](http://svn.apache.org/repos/asf/sling/trunk/launchpad/builder) - produces an application descriptor. + * [org.apache.sling.launchpad.testing](http://svn.apache.org/repos/asf/sling/trunk/launchpad/testing/) - uses the application descriptor from `org.apache.sling.launchpad` and adds two bundles. -Maven Launchpad Plugin provides the following goals: +Maven Launchpad Plugin provides the following goals: -| Goals | Description | +| Goals | Description | |--|--| -| launchpad:prepare-package | Create the file system structure required by Sling's Launchpad framework. | -| launchpad:attach-bundle-list | Attach the bundle list descriptor to the current project as a Maven artifact. | -| launchpad:create-karaf-descriptor | Create an Apache Karaf Feature descriptor. | -| launchpad:create-bundle-jar | Create a JAR file containing the bundles in a Launchpad-structured JAR file. | -| launchpad:check-bundle-list-for-snapshots | Validate that the bundle list does not contain any SNAPSHOT versions. | +| launchpad:prepare-package | Create the file system structure required by Sling's Launchpad framework. | +| launchpad:attach-bundle-list | Attach the bundle list descriptor to the current project as a Maven artifact. | +| launchpad:create-karaf-descriptor | Create an Apache Karaf Feature descriptor. | +| launchpad:create-bundle-jar | Create a JAR file containing the bundles in a Launchpad-structured JAR file. | +| launchpad:check-bundle-list-for-snapshots | Validate that the bundle list does not contain any SNAPSHOT versions. | | launchpad:run | Run a Launchpad application. | | launchpad:start | Start a Launchpad application. | | launchpad:stop | Stop a Launchpad application. | @@ -38,11 +41,11 @@ Maven Launchpad Plugin provides the following goals: In general, the bulk of the configuration of the Maven Launchpad Plugin is concerned with setting up the bundle list which all of the goals will use. This bundle list is created using the following steps: -1. If `includeDefaultBundles` is `true` (the default), the default bundle list is loaded. By default, this is `org.apache.sling.launchpad:org.apache.sling.launchpad:RELEASE:xml:bundlelist`, but can be overridden by setting the `defaultBundleList` plugin parameter. -1. If `includeDefaultBundles` is `false`, an empty list is created. -1. If the bundle list file exists (by default, at `src/main/bundles/list.xml`), the bundles defined in it are added to the bundle list. -1. If the `additionalBundles` plugin parameter is defined, those bundles are added to the bundle list. -1. If the `bundleExclusions` plugin parameter is defined, those bundles are removed from the bundle list. + 1. If `includeDefaultBundles` is `true` (the default), the default bundle list is loaded. By default, this is `org.apache.sling.launchpad:org.apache.sling.launchpad:RELEASE:xml:bundlelist`, but can be overridden by setting the `defaultBundleList` plugin parameter. + 1. If `includeDefaultBundles` is `false`, an empty list is created. + 1. If the bundle list file exists (by default, at `src/main/bundles/list.xml`), the bundles defined in it are added to the bundle list. + 1. If the `additionalBundles` plugin parameter is defined, those bundles are added to the bundle list. + 1. If the `bundleExclusions` plugin parameter is defined, those bundles are removed from the bundle list. When a bundle is added to the bundle list, if a bundle with the same groupId, artifactId, type, and classifier is already in the bundle list, the version of the existing bundle is modified. However, the start level of a bundle is never changed once that bundle is added to the bundle list. @@ -52,7 +55,7 @@ The plugin may also contribute bundles to (or remove bundles from) the bundle li For the `run` and `start` goals, the plugin will look for a file named `src/test/config/sling.properties`. If this file is present, it will be filtered using standard Maven filtering and used to populate the OSGi framework properties. This can be used, for example, to specify a `repository.xml` file to be used during development: -sling.repository.config.file.url=${basedir}/src/test/config/repository.xml + sling.repository.config.file.url=${basedir}/src/test/config/repository.xml ## Bundle List Files @@ -60,37 +63,37 @@ sling.repository.config.file.url=${basedir}/src/test/config/repository.xml The bundle list file uses a simple XML syntax representing a list of bundles organized into start levels: -<?xml version="1.0"?> -<bundles> -<startLevel level="0"> -<bundle> -<groupId>commons-io</groupId> -<artifactId>commons-io</artifactId> -<version>1.4</version> -</bundle> -<bundle> -<groupId>commons-collections</groupId> -<artifactId>commons-collections</artifactId> -<version>3.2.1</version> -</bundle> -</startLevel> - -<startLevel level="10"> -<bundle> -<groupId>org.apache.felix</groupId> -<artifactId>org.apache.felix.eventadmin</artifactId> -<version>1.0.0</version> -</bundle> -</startLevel> - -<startLevel level="15"> -<bundle> -<groupId>org.apache.sling</groupId> -<artifactId>org.apache.sling.jcr.api</artifactId> -<version>2.0.2-incubator</version> -</bundle> -</startLevel> -</bundles> + <?xml version="1.0"?> + <bundles> + <startLevel level="0"> + <bundle> + <groupId>commons-io</groupId> + <artifactId>commons-io</artifactId> + <version>1.4</version> + </bundle> + <bundle> + <groupId>commons-collections</groupId> + <artifactId>commons-collections</artifactId> + <version>3.2.1</version> + </bundle> + </startLevel> + + <startLevel level="10"> + <bundle> + <groupId>org.apache.felix</groupId> + <artifactId>org.apache.felix.eventadmin</artifactId> + <version>1.0.0</version> + </bundle> + </startLevel> + + <startLevel level="15"> + <bundle> + <groupId>org.apache.sling</groupId> + <artifactId>org.apache.sling.jcr.api</artifactId> + <version>2.0.2-incubator</version> + </bundle> + </startLevel> + </bundles> Within each `bundle` element, `type` and `classifier` are also supported. @@ -102,47 +105,47 @@ The Http Service support can not be configured using the bundle list, but only u The `defaultBundleList`, `jarWebSupport`, `additionalBundles`, and `bundleExclusions` parameters are configured with artifact definitions. This is done using a syntax similar to Maven dependency elements: -<configuration> -... -<jarWebSupport> -<groupId>GROUP_ID</groupId> -<artifactId>ARTIFACT_ID</artifactId> -<version>VERSION</version> -<!-- type and classifier can also be specified if needed --> -</jarWebSupport> -... -</configuration> + <configuration> + ... + <jarWebSupport> + <groupId>GROUP_ID</groupId> + <artifactId>ARTIFACT_ID</artifactId> + <version>VERSION</version> + <!-- type and classifier can also be specified if needed --> + </jarWebSupport> + ... + </configuration> For example, to use Pax Web instead of Felix HttpService as the HttpService provider, use the following: -<configuration> -... -<jarWebSupport> -<groupId>org.ops4j.pax.web</groupId> -<artifactId>pax-web-service</artifactId> -<version>RELEASE</version> -<!-- type and classifier can also be specified if needed --> -</jarWebSupport> -... -</configuration> + <configuration> + ... + <jarWebSupport> + <groupId>org.ops4j.pax.web</groupId> + <artifactId>pax-web-service</artifactId> + <version>RELEASE</version> + <!-- type and classifier can also be specified if needed --> + </jarWebSupport> + ... + </configuration> In the case of `additionalBundles` and `bundleExclusions`, these are arrays of definitions, so an intermediate `bundle` element is necessary: -<configuration> -... -<additionalBundles> -<bundle> -<groupId>GROUP_ID</groupId> -<artifactId>ARTIFACT_ID</artifactId> -<version>VERSION</version> -<!-- type and classifier can also be specified if needed --> -</bundle> -</additionalBundles> -... -</configuration> + <configuration> + ... + <additionalBundles> + <bundle> + <groupId>GROUP_ID</groupId> + <artifactId>ARTIFACT_ID</artifactId> + <version>VERSION</version> + <!-- type and classifier can also be specified if needed --> + </bundle> + </additionalBundles> + ... + </configuration> By default, bundles are added to start level 0. To change, this use the `startLevel` element within each additional bundle definition. @@ -157,5 +160,5 @@ The Maven Launchpad Plugin supports the use of rules to rewrite the bundle list. In order for rules to interact with the Maven build, the following global variables are made available: -* `mavenSession` - an instance of `org.apache.maven.execution.MavenSession`. -* `mavenProject` - an instance of `org.apache.maven.project.MavenProject`. + * `mavenSession` - an instance of `org.apache.maven.execution.MavenSession`. + * `mavenProject` - an instance of `org.apache.maven.project.MavenProject`. http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/development/maven-usage.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/maven-usage.md b/content/documentation/development/maven-usage.md index 44757c7..ae1bc27 100644 --- a/content/documentation/development/maven-usage.md +++ b/content/documentation/development/maven-usage.md @@ -1,7 +1,10 @@ -title=Maven Usage -type=page +title=TODO title for maven-usage.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Maven Usage Apache Sling uses Maven as a build tool. This page documents some of the choices that we made when using Maven. @@ -11,13 +14,13 @@ We separate the reactor POM from the parent POM. While the reactor POM functions The reference to the parent POM is usually set to a released version since we don't deploy it as a SNAPSHOT during the build process. That reference must also contain an empty parentPath element, otherwise recent version of Maven will try to find it in the local filesystem, disregarding the version if the groupId and artifactId match. An example of how to reference the parent POM is -#!xml -<parent> -<groupId>org.apache.sling</groupId> -<artifactId>sling</artifactId> -<version>$VERSION</version> -<relativePath/> -</parent> + #!xml + <parent> + <groupId>org.apache.sling</groupId> + <artifactId>sling</artifactId> + <version>$VERSION</version> + <relativePath/> + </parent> Where `$VERSION` is replaced by the latest parent POM version. http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/development/maventipsandtricks.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/maventipsandtricks.md b/content/documentation/development/maventipsandtricks.md index 53f4fc4..5fcfd1f 100644 --- a/content/documentation/development/maventipsandtricks.md +++ b/content/documentation/development/maventipsandtricks.md @@ -1,8 +1,11 @@ -title=MavenTipsAndTricks -type=page +title=TODO title for maventipsandtricks.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ translation_pending: true +Title: MavenTipsAndTricks Here's our collection of tips and tricks for building Sling with [Maven](http://maven.apache.org). @@ -24,7 +27,7 @@ To make sure you're getting the same results as we are when building Sling, it i On unixish platforms, using -mvn -s /dev/null ... + mvn -s /dev/null ... does the trick. @@ -33,7 +36,7 @@ does the trick. Does anyone have a similar command-line option that works under Windows? </div> -# +# # MAVEN_OPTS The MAVEN_OPTS environment variable defines options for the JVM that executes Maven. @@ -43,7 +46,7 @@ Set it according to your platform, i.e. `export MAVEN*OPTS=...` on unixish syste If getting an OutOfMemoryException when running mvn, try setting -MAVEN_OPTS="-Xmx256M -XX:MaxPermSize=256m" + MAVEN_OPTS="-Xmx256M -XX:MaxPermSize=256m" to allocate 256MB of RAM to Maven. @@ -52,7 +55,7 @@ to allocate 256MB of RAM to Maven. To run the Sling launchpad webapp in debug mode from Maven, for example, use something like -MAVEN_OPTS="-agentlib:jdwp=transport=dt_socket,address=30303,server=y,suspend=n" + MAVEN_OPTS="-agentlib:jdwp=transport=dt_socket,address=30303,server=y,suspend=n" And then connect to port 30303 with a remote JVM debugger (most IDEs do this). http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/development/monitoring-requests.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/monitoring-requests.md b/content/documentation/development/monitoring-requests.md index f2b1cbf..b9c9523 100644 --- a/content/documentation/development/monitoring-requests.md +++ b/content/documentation/development/monitoring-requests.md @@ -1,7 +1,10 @@ -title=Monitoring Requests -type=page +title=TODO title for monitoring-requests.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: Monitoring Requests Sling provides a simple OSGi console plugin to monitor recent requests. This is quite useful when debugging and to understand how things work, though it's obviously not a replacement for full-blown HTTP trafic monitoring tools. http://git-wip-us.apache.org/repos/asf/sling-site/blob/53c84cf9/content/documentation/development/osgi-mock.md ---------------------------------------------------------------------- diff --git a/content/documentation/development/osgi-mock.md b/content/documentation/development/osgi-mock.md index bf76a83..e140803 100644 --- a/content/documentation/development/osgi-mock.md +++ b/content/documentation/development/osgi-mock.md @@ -1,7 +1,10 @@ -title=OSGi Mocks -type=page +title=TODO title for osgi-mock.md +date=1900-01-01 +type=post +tags=blog status=published ~~~~~~ +Title: OSGi Mocks Mock implementation of selected OSGi APIs for easier testing. @@ -10,11 +13,11 @@ Mock implementation of selected OSGi APIs for easier testing. ## Maven Dependency -#!xml -<dependency> -<groupId>org.apache.sling</groupId> -<artifactId>org.apache.sling.testing.osgi-mock</artifactId> -</dependency> + #!xml + <dependency> + <groupId>org.apache.sling</groupId> + <artifactId>org.apache.sling.testing.osgi-mock</artifactId> + </dependency> See latest version on the [downloads page](/downloads.cgi). @@ -50,30 +53,30 @@ Since osgi-mock 2.0.0: ### OSGi Context JUnit Rule The OSGi mock context can be injected into a JUnit test using a custom JUnit rule named `OsgiContext`. -This rules takes care of all initialization and cleanup tasks required to make sure all unit tests can run +This rules takes care of all initialization and cleanup tasks required to make sure all unit tests can run independently (and in parallel, if required). Example: -#!java -public class ExampleTest { + #!java + public class ExampleTest { -@Rule -public final OsgiContext context = new OsgiContext(); + @Rule + public final OsgiContext context = new OsgiContext(); -@Test -public void testSomething() { + @Test + public void testSomething() { -// register and activate service with configuration -MyService service1 = context.registerInjectActivateService(new MyService(), -"prop1", "value1"); + // register and activate service with configuration + MyService service1 = context.registerInjectActivateService(new MyService(), + "prop1", "value1"); -// get service instance -OtherService service2 = context.getService(OtherService.class); + // get service instance + OtherService service2 = context.getService(OtherService.class); -} + } -} + } It is possible to combine such a unit test with a `@RunWith` annotation e.g. for [Mockito JUnit Runner][mockito-testrunner]. @@ -94,23 +97,23 @@ The factory class `MockOsgi` allows to instantiate the different mock implementa Example: -#!java -// get bundle context -BundleContext bundleContext = MockOsgi.newBundleContext(); + #!java + // get bundle context + BundleContext bundleContext = MockOsgi.newBundleContext(); -// get component context with configuration -BundleContext bundleContext = MockOsgi.newComponentContext(properties, -"prop1", "value1"); + // get component context with configuration + BundleContext bundleContext = MockOsgi.newComponentContext(properties, + "prop1", "value1"); It is possible to simulate registering of OSGi services (backed by a simple hash map internally): -#!java -// register service -bundleContext.registerService(MyClass.class, myService, properties); + #!java + // register service + bundleContext.registerService(MyClass.class, myService, properties); -// get service instance -ServiceReference ref = bundleContext.getServiceReference(MyClass.class.getName()); -MyClass service = bundleContext.getService(ref); + // get service instance + ServiceReference ref = bundleContext.getServiceReference(MyClass.class.getName()); + MyClass service = bundleContext.getService(ref); ### Activation and Dependency Injection @@ -120,27 +123,27 @@ tries to to its best to execute all as expected for an OSGi environment. Example: -#!java -// get bundle context -BundleContext bundleContext = MockOsgi.newBundleContext(); + #!java + // get bundle context + BundleContext bundleContext = MockOsgi.newBundleContext(); -// create service instance manually -MyService service = new MyService(); + // create service instance manually + MyService service = new MyService(); -// inject dependencies -MockOsgi.injectServices(service, bundleContext); + // inject dependencies + MockOsgi.injectServices(service, bundleContext); -// activate service -MockOsgi.activate(service, props); + // activate service + MockOsgi.activate(service, props); -// operate with service... + // operate with service... -// deactivate service -MockOsgi.deactivate(service); + // deactivate service + MockOsgi.deactivate(service); Please note: -* You should ensure that you register you services in the correct order of their dependency chain. +* You should ensure that you register you services in the correct order of their dependency chain. Only dynamic references will be handled automatically independent of registration order. * The injectServices, activate and deactivate Methods can only work properly when the SCR XML metadata files are preset in the classpath at `/OSGI-INF`. They are generated automatically by the Maven SCR plugin, but might be @@ -154,13 +157,13 @@ If you want to provide your own configuration to an OSGi service that you do not Example: -#!java + #!java -ConfigurationAdmin configAdmin = context.getService(ConfigurationAdmin.class); -Configuration myServiceConfig = configAdmin.getConfiguration(MY_SERVICE_PID); -Dictionary<String, Object> props = new Hashtable<String, Object>(); -props.put("prop1", "value1"); -myServiceConfig.update(props); + ConfigurationAdmin configAdmin = context.getService(ConfigurationAdmin.class); + Configuration myServiceConfig = configAdmin.getConfiguration(MY_SERVICE_PID); + Dictionary<String, Object> props = new Hashtable<String, Object>(); + props.put("prop1", "value1"); + myServiceConfig.update(props); ### Context Plugins @@ -171,11 +174,11 @@ To define a plugin implement the `org.apache.sling.testing.mock.osgi.context.Con To use a plugin in your unit test class, use the `OsgiContextBuilder` class instead of directly instantiating the `OsgiContext`class. This allows you in a fluent style to configure more options, with the `plugin(...)` method you can add one or more plugins. -Example: +Example: -#!java -@Rule -public OsgiContext context = new OsgiContextBuilder().plugin(MY_PLUGIN).build(); + #!java + @Rule + public OsgiContext context = new OsgiContextBuilder().plugin(MY_PLUGIN).build(); More examples:
