Chapter 15. URL Handlers There are many contexts in Red Hat Fuse where you need to provide a URL to specify the location of a resource (for example, as the argument to a console command). In general, when specifying a URL, you can use any of the schemes supported by Fuse's built-in URL handlers. This appendix describes the syntax for all of the available URL handlers. 15.1. File URL Handler 15.1.1. Syntax A file URL has the syntax, file: PathName , where PathName is the relative or absolute pathname of a file that is available on the Classpath. The provided PathName is parsed by Java's built-in file URL handler . Hence, the PathName syntax is subject to the usual conventions of a Java pathname: in particular, on Windows, each backslash must either be escaped by another backslash or replaced by a forward slash. 15.1.2. Examples For example, consider the pathname, C:\Projects\camel-bundle\target\foo-1.0-SNAPSHOT.jar , on Windows. The following example shows the correct alternatives for the file URL on Windows: The following example shows some incorrect alternatives for the file URL on Windows: 15.2. HTTP URL Handler 15.2.1. Syntax A HTTP URL has the standard syntax, http: Host [: Port ]/[ Path ][# AnchorName ][? Query ] . You can also specify a secure HTTP URL using the https scheme. The provided HTTP URL is parsed by Java's built-in HTTP URL handler, so the HTTP URL behaves in the normal way for a Java application. 15.3. Mvn URL Handler 15.3.1. Overview If you use Maven to build your bundles or if you know that a particular bundle is available from a Maven repository, you can use the Mvn handler scheme to locate the bundle. Note To ensure that the Mvn URL handler can find local and remote Maven artifacts, you might find it necessary to customize the Mvn URL handler configuration. For details, see Section 15.3.5, "Configuring the Mvn URL handler" . 15.3.2. Syntax An Mvn URL has the following syntax: Where repositoryUrl optionally specifies the URL of a Maven repository. The groupId , artifactId , version , packaging , and classifier are the standard Maven coordinates for locating Maven artifacts. 15.3.3. Omitting coordinates When specifying an Mvn URL, only the groupId and the artifactId coordinates are required. The following examples reference a Maven bundle with the groupId , org.fusesource.example , and with the artifactId , bundle-demo : When the version is omitted, as in the first example, it defaults to LATEST , which resolves to the latest version based on the available Maven metadata. In order to specify a classifier value without specifying a packaging or a version value, it is permissible to leave gaps in the Mvn URL. Likewise, if you want to specify a packaging value without a version value. For example: 15.3.4. Specifying a version range When specifying the version value in an Mvn URL, you can specify a version range (using standard Maven version range syntax) in place of a simple version number. You use square brackets- [ and ] -to denote inclusive ranges and parentheses- ( and ) -to denote exclusive ranges. For example, the range, [1.0.4,2.0) , matches any version, v , that satisfies 1.0.4 ⇐ v < 2.0 . You can use this version range in an Mvn URL as follows: 15.3.5. Configuring the Mvn URL handler Before using Mvn URLs for the first time, you might need to customize the Mvn URL handler settings, as follows: Section 15.3.6, "Check the Mvn URL settings" . Section 15.3.7, "Edit the configuration file" . Section 15.3.8, "Customize the location of the local repository" . 15.3.6. Check the Mvn URL settings The Mvn URL handler resolves a reference to a local Maven repository and maintains a list of remote Maven repositories. When resolving an Mvn URL, the handler searches first the local repository and then the remote repositories in order to locate the specified Maven artifiact. If there is a problem with resolving an Mvn URL, the first thing you should do is to check the handler settings to see which local repository and remote repositories it is using to resolve URLs. To check the Mvn URL settings, enter the following commands at the console: The config:edit command switches the focus of the config utility to the properties belonging to the org.ops4j.pax.url.mvn persistent ID. The config:proplist command outputs all of the property settings for the current persistent ID. With the focus on org.ops4j.pax.url.mvn , you should see a listing similar to the following: Where the localRepository setting shows the local repository location currently used by the handler and the repositories setting shows the remote repository list currently used by the handler. 15.3.7. Edit the configuration file To customize the property settings for the Mvn URL handler, edit the following configuration file: The settings in this file enable you to specify explicitly the location of the local Maven repository, remove Maven repositories, Maven proxy server settings, and more. Please see the comments in the configuration file for more details about these settings. 15.3.8. Customize the location of the local repository In particular, if your local Maven repository is in a non-default location, you might find it necessary to configure it explicitly in order to access Maven artifacts that you build locally. In your org.ops4j.pax.url.mvn.cfg configuration file, uncomment the org.ops4j.pax.url.mvn.localRepository property and set it to the location of your local Maven repository. For example: 15.3.9. Reference For more details about the mvn URL syntax, see the original Pax URL Mvn Protocol documentation. 15.4. Wrap URL Handler 15.4.1. Overview If you need to reference a JAR file that is not already packaged as a bundle, you can use the Wrap URL handler to convert it dynamically. The implementation of the Wrap URL handler is based on Peter Krien's open source Bnd utility. 15.4.2. Syntax A Wrap URL has the following syntax: The locationURL can be any URL that locates a JAR (where the referenced JAR is not formatted as a bundle). The optional instructionsURL references a Bnd properties file that specifies how the bundle conversion is performed. The optional instructions is an ampersand, & , delimited list of Bnd properties that specify how the bundle conversion is performed. 15.4.3. Default instructions In most cases, the default Bnd instructions are adequate for wrapping an API JAR file. By default, Wrap adds manifest headers to the JAR's META-INF/Manifest.mf file as shown in Table 15.1, "Default Instructions for Wrapping a JAR" . Table 15.1. Default Instructions for Wrapping a JAR Manifest Header Default Value Import-Package *;resolution:=optional Export-Package All packages from the wrapped JAR. Bundle-SymbolicName The name of the JAR file, where any characters not in the set [a-zA-Z0-9_-] are replaced by underscore, _ . 15.4.4. Examples The following Wrap URL locates version 1.1 of the commons-logging JAR in a Maven repository and converts it to an OSGi bundle using the default Bnd properties: The following Wrap URL uses the Bnd properties from the file, E:\Data\Examples\commons-logging-1.1.bnd : The following Wrap URL specifies the Bundle-SymbolicName property and the Bundle-Version property explicitly: If the preceding URL is used as a command-line argument, it might be necessary to escape the dollar sign, \USD , to prevent it from being processed by the command line, as follows: 15.4.5. Reference For more details about the wrap URL handler, see the following references: The Bnd tool documentation , for more details about Bnd properties and Bnd instruction files. The original Pax URL Wrap Protocol documentation. 15.5. War URL Handler 15.5.1. Overview If you need to deploy a WAR file in an OSGi container, you can automatically add the requisite manifest headers to the WAR file by prefixing the WAR URL with war: , as described here. 15.5.2. Syntax A War URL is specified using either of the following syntaxes: The first syntax, using the war scheme, specifies a WAR file that is converted into a bundle using the default instructions. The warURL can be any URL that locates a WAR file. The second syntax, using the warref scheme, specifies a Bnd properties file, instructionsURL , that contains the conversion instructions (including some instructions that are specific to this handler). In this syntax, the location of the referenced WAR file does not appear explicitly in the URL. The WAR file is specified instead by the (mandatory) WAR-URL property in the properties file. 15.5.3. WAR-specific properties/instructions Some of the properties in the .bnd instructions file are specific to the War URL handler, as follows: WAR-URL (Mandatory) Specifies the location of the War file that is to be converted into a bundle. Web-ContextPath Specifies the piece of the URL path that is used to access this Web application, after it has been deployed inside the Web container. Note Earlier versions of PAX Web used the property, Webapp-Context , which is now deprecated . 15.5.4. Default instructions By default, the War URL handler adds manifest headers to the WAR's META-INF/Manifest.mf file as shown in Table 15.2, "Default Instructions for Wrapping a WAR File" . Table 15.2. Default Instructions for Wrapping a WAR File Manifest Header Default Value Import-Package javax. ,org.xml. ,org.w3c.* Export-Package No packages are exported. Bundle-SymbolicName The name of the WAR file, where any characters not in the set [a-zA-Z0-9_-\.] are replaced by period, . . Web-ContextPath No default value. But the WAR extender will use the value of Bundle-SymbolicName by default. Bundle-ClassPath In addition to any class path entries specified explicitly, the following entries are added automatically: . WEB-INF/classes All of the JARs from the WEB-INF/lib directory. 15.5.5. Examples The following War URL locates version 1.4.7 of the wicket-examples WAR in a Maven repository and converts it to an OSGi bundle using the default instructions: The following Wrap URL specifies the Web-ContextPath explicitly: The following War URL converts the WAR file referenced by the WAR-URL property in the wicket-examples-1.4.7.bnd file and then converts the WAR into an OSGi bundle using the other instructions in the .bnd file: 15.5.6. Reference For more details about the war URL syntax, see the original Pax URL War Protocol documentation.

Commands:
file:C:/Projects/camel-bundle/target/foo-1.0-SNAPSHOT.jar file:C:\\Projects\\camel-bundle\\target\\foo-1.0-SNAPSHOT.jar
file:C:\Projects\camel-bundle\target\foo-1.0-SNAPSHOT.jar // WRONG! file://C:/Projects/camel-bundle/target/foo-1.0-SNAPSHOT.jar // WRONG! file://C:\\Projects\\camel-bundle\\target\\foo-1.0-SNAPSHOT.jar // WRONG!
mvn:[ repositoryUrl !] groupId / artifactId [/[ version ][/[ packaging ][/[ classifier ]]]]
mvn:org.fusesource.example/bundle-demo mvn:org.fusesource.example/bundle-demo/1.1
mvn: groupId / artifactId /// classifier mvn: groupId / artifactId / version // classifier mvn: groupId / artifactId // packaging / classifier mvn: groupId / artifactId // packaging
mvn:org.fusesource.example/bundle-demo/[1.0.4,2.0)
JBossFuse:karaf@root> config:edit org.ops4j.pax.url.mvn JBossFuse:karaf@root> config:proplist
org.ops4j.pax.url.mvn.defaultRepositories = file:/path/to/JBossFuse/jboss-fuse-7.13.0.fuse-7_13_0-00012-redhat-00001/system@snapshots@id=karaf.system,file:/home/userid/.m2/repository@snapshots@id=local,file:/path/to/JBossFuse/jboss-fuse-7.13.0.fuse-7_13_0-00012-redhat-00001/local-repo@snapshots@id=karaf.local-repo,file:/path/to/JBossFuse/jboss-fuse-7.13.0.fuse-7_13_0-00012-redhat-00001/system@snapshots@id=child.karaf.system org.ops4j.pax.url.mvn.globalChecksumPolicy = warn org.ops4j.pax.url.mvn.globalUpdatePolicy = daily org.ops4j.pax.url.mvn.localRepository = /path/to/JBossFuse/jboss-fuse-7.13.0.fuse-7_13_0-00012-redhat-00001/data/repository org.ops4j.pax.url.mvn.repositories = http://repo1.maven.org/maven2@id=maven.central.repo, https://maven.repository.redhat.com/ga@id=redhat.ga.repo, https://maven.repository.redhat.com/earlyaccess/all@id=redhat.ea.repo, https://repository.jboss.org/nexus/content/groups/ea@id=fuseearlyaccess org.ops4j.pax.url.mvn.settings = /path/to/jboss-fuse-7.13.0.fuse-7_13_0-00012-redhat-00001/etc/maven-settings.xml org.ops4j.pax.url.mvn.useFallbackRepositories = false service.pid = org.ops4j.pax.url.mvn
InstallDir /etc/org.ops4j.pax.url.mvn.cfg
Path to the local maven repository which is used to avoid downloading artifacts when they already exist locally. The value of this property will be extracted from the settings.xml file above, or defaulted to: System.getProperty( "user.home" ) + "/.m2/repository" # org.ops4j.pax.url.mvn.localRepository=file:E:/Data/.m2/repository
wrap: locationURL [, instructionsURL ][USD instructions ]
wrap:mvn:commons-logging/commons-logging/1.1
wrap:mvn:commons-logging/commons-logging/1.1,file:E:/Data/Examples/commons-logging-1.1.bnd
wrap:mvn:commons-logging/commons-logging/1.1USDBundle-SymbolicName=apache-comm-log&Bundle-Version=1.1
wrap:mvn:commons-logging/commons-logging/1.1\USDBundle-SymbolicName=apache-comm-log&Bundle-Version=1.1
war: warURL warref: instructionsURL
war:mvn:org.apache.wicket/wicket-examples/1.4.7/war
war:mvn:org.apache.wicket/wicket-examples/1.4.7/war?Web-ContextPath=wicket
warref:file:E:/Data/Examples/wicket-examples-1.4.7.bnd