juneau-doc/docs/Topics/03.juneau-marshall-rdf/01.RdfDetails/05.UriProperties.html

<!--
/***************************************************************************************************************************
 * 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.
 ***************************************************************************************************************************/
 -->

URI Properties

<p>
	Bean properties of type <c>java.net.URI</c> or <c>java.net.URL</c> have special meaning to the 
	RDF serializer.
	They are interpreted as resource identifiers.
</p>
<p>
	In the following code, we're adding 2 new properties.
	The first property is annotated with <ja>@Beanp</ja> to identify that this property is the resource 
	identifier for this bean.
	The second un-annotated property is interpreted as a reference to another resource.
</p>
<p class='bpcode w800'>	
	<jk>public class</jk> Person {
		
		<jc>// Bean properties</jc>
		<ja>@Rdf</ja>(beanUri=<jk>true</jk>) 
		<jk>public</jk> URI <jf>uri</jf>;
		
		<jk>public</jk> URI <jf>addressBookUri</jf>;
	
		...
		
		<jc>// Normal constructor</jc>
		<jk>public</jk> Person(<jk>int</jk> id, String name, String uri, String addressBookUri) <jk>throws</jk> URISyntaxException {
			<jk>this</jk>.<jf>id</jf> = id;
			<jk>this</jk>.<jf>name</jf> = name;
			<jk>this</jk>.<jf>uri</jf> = <jk>new</jk> URI(uri);
			<jk>this</jk>.<jf>addressBookUri</jf> = <jk>new</jk> URI(addressBookUri);
		}
	}
</p>
<p>
	We alter our code to pass in values for these new properties.
</p>
<p class='bpcode w800'>
	<jc>// Create our bean.</jc>
	Person p = <jk>new</jk> Person(1, <js>"John Smith"</js>, <js>"http://sample/addressBook/person/1"</js>, 
		<js>"http://sample/addressBook"</js>);
</p>
<p>
	Now when we run the sample code, we get the following:
</p>
<p class='bpcode w800'>
	<xt>&lt;rdf:RDF</xt>
	    <xa>xmlns:rdf</xa>=<xs>"http://www.w3.org/1999/02/22-rdf-syntax-ns#"</xs>
	    <xa>xmlns:j</xa>=<xs>"http://www.apache.org/juneau/"</xs>
	    <xa>xmlns:jp</xa>=<xs>"http://www.apache.org/juneaubp/"</xs>
	    <xa>xmlns:per</xa>=<xs>"http://www.apache.org/person/"</xs><xt>&gt;</xt>
	   <xt>&lt;rdf:Description <b><xa>rdf:about</xa>=<xs>"http://sample/addressBook/person/1"</xs></b>&gt;</xt>
	      <xt>&lt;per:addressBookUri</xt> <xa>rdf:resource</xa>=<xs>"http://sample/addressBook"</xs><xt>/&gt;</xt>
	      <xt>&lt;per:id&gt;</xt>1<xt>&lt;/per:id&gt;</xt>
	      <xt>&lt;per:name&gt;</xt>John Smith<xt>&lt;/per:name&gt;</xt>
	   <xt>&lt;/rdf:Description&gt;</xt>
	<xt>&lt;/rdf:RDF&gt;</xt>
</p>
<p>
	The {@link oaj.annotation.URI @URI} annotation can also be used on classes and properties 
	to identify them as URLs when they're not instances of <c>java.net.URI</c> or <c>java.net.URL</c> 
	(not needed if <c><ja>@Rdf</ja>(beanUri=<jk>true</jk>)</c> is already specified).
</p>
<p>
	The following properties would have produced the same output as before.  
	Note that the <ja>@URI</ja> annotation is only needed on the second property.
</p>
<p class='bpcode w800'>
	<jk>public class</jk> Person {
		
		<jc>// Bean properties</jc>
		<ja>@Rdf</ja>(beanUri=<jk>true</jk>) <jk>public</jk> String <jf>uri</jf>;
		
		<ja>@URI</ja> <jk>public</jk> String <jf>addressBookUri</jf>;
</p>
<p>
	Also take note of the {@link oaj.serializer.Serializer#SERIALIZER_uriResolution},
	{@link oaj.serializer.Serializer#SERIALIZER_uriRelativity}, and 
	and {@link oaj.serializer.Serializer#SERIALIZER_uriContext}
	settings that can be specified on the serializer to resolve relative and context-root-relative URIs to 
	fully-qualified URIs.
</p>
<p>
	This can be useful if you want to keep the URI authority and context root information out of the bean logic 
	layer.
</p>
<p>
	The following code produces the same output as before, but the URIs on the beans are relative.
</p>
<p class='bpcode w800'>
	<jc>// Create a new serializer with readable output.</jc>
	RdfSerializer s = RdfSerializer.<jsm>create</jsm>()
		.xmlabbrev()
		.set(RdfProperties.<jsf>RDF_rdfxml_tab</jsf>, 3);
		.relativeUriBase(<js>"http://myhost/sample"</js>);
		.absolutePathUriBase(<js>"http://myhost"</js>)
		.build();
		
	<jc>// Create our bean.</jc>
	Person p = <jk>new</jk> Person(1, <js>"John Smith"</js>, <js>"person/1"</js>, <js>"/"</js>);

	<jc>// Serialize the bean to RDF/XML.</jc>
	String rdfXml = s.serialize(p);
</p>