Views

TOOLBOX

LANGUAGES

DDR-RI User Manual

From Morfeo Wiki

Jump to: navigation, search

Contents

Introduction

This manual details how users can use the Device Information Simple API (implementation of W3C's DDR Simple API specification).

Download

Configuration

This implementation uses different properties to configure your DevInfo Simple API application.

Required properties

  • Property org.morfeo.devinfo.simple.data
    • It's the path to resources (descriptors, mappings, data sources, etc).
    • E.g. /apps/DevInfo-Simple-1.0/resources.

Optional properties

  • Property org.morfeo.devinfo.simple.vocabularies
  • Property org.morfeo.devinfo.simple.Service.default
    • Set the default service.
    • If this property is not defined the default service will be org.morfeo.devinfo.simple.ServiceImpl
  • Property org.morfeo.devinfo.simple.sources
    • List of available data sources (comma-separated data sources names).
    • This implementation will connect to all data sources defined on source.xml if this property is not defined.
    • Note: If you want use WURFL as data source you have to append to JVM parameters '-Xms512m -Xmx512m'
  • Property org.morfeo.devinfo.simple.timeout
    • Timeout to calculate the profile (in seconds).
    • 5 seconds for default.
  • Property org.morfeo.devinfo.simple.retry
    • Maximum number of attempts to calculate the profile (in seconds). If this value is exceeded the service will not attempt it.
    • 5 seconds for default.

How to use (with sample code)

Initialization 

Properties properties = new Properties();
properties.setProperty(Constants.PATH_PROPERTY, "/home/crdlc/myapp/devInfo-0.9.5/resources");

Service service = ServiceFactory.newService(ServiceImpl.class.getName(),"http://www.w3.org/2008/01/ddr-core-vocabulary", properties);
  • Create new default Service with default vocabulary 'http://www.w3.org/2008/01/ddr-core-vocabulary'. The default Service is org.morfeo.devinfo.simple.ServiceImpl beacause the org.morfeo.devinfo.simple.Service.default property is not defined. 
Properties properties = new Properties();
properties.setProperty(Constants.PATH_PROPERTY, "/home/crdlc/myapp/devInfo-0.9.5/resources");

Service service = ServiceFactoryExt.newDefaultService("http://www.w3.org/2008/01/ddr-core-vocabulary", properties);

Factory Methods

Create HTTP Evidence

  • Create empty HTTP Evidence 
Evidence evidence = service.newHTTPEvidence();
  • Create HTTP Evidence from Map for Nokia 9500 device. 
Map<String, String> headers = new HashMap<String, String>();
headers.put("User-Agent", "Nokia9500");
headers.put("x-wap-profile","http://nds1.nds.nokia.com/uaprof/N9500r100.xml");
Evidence evidence = service.newHTTPEvidence(headers);

Create PropertyName 

PropertyName propertyName = service.newPropertyName("cookieSupport");

PropertyName propertyName = service.newPropertyName("accesskeySupport", "http://morfeo-project.org/mymobileweb");

Create PropertyRef 

PropertyRef propertyRef = service.newPropertyRef("vendor");
  • Create PropertyRef from PropertyName using Default Aspect.
    • The Aspect of the PropertyRef created is the default Aspect of the Property in the Vocabulary determined by the propertyName parameter (webBrowser for accesskeySupport property). 
PropertyName propertyName = service.newPropertyName("accesskeySupport", "http://morfeo-project.org/mymobileweb");
PropertyRef propertyRef = service.newPropertyRef(propertyName);
  • Create PropertyRef from PropertyName in Named Aspect
    • The namespace associated with the Aspect localAspectName is associated with the namespace of the propertyName parameter. 
PropertyName propertyName = service.newPropertyName("rendersTables", "http://morfeo-project.org/mymobileweb");
PropertyRef propertyRef = service.newPropertyRef(propertyName, Constants.WEB_BROWSER);

Query Methods

Return Known Values

  • Return all available Property values for all the Aspects and Vocabularies known by this implementation. 
PropertyValues propertyValues = service.getPropertyValues(evidence);
PropertyValue[] values = propertyValues.getAll();
for (int i = 0; i < values.length; i++) {
   PropertyValue propertyValue = values[i];
   ............
}
  • Return all known values for the given Aspect of the Default Vocabulary
    • Aspect: webBrowser. 
PropertyValues propertyValues = service.getPropertyValues(evidence, Constants.WEB_BROWSER);
PropertyValue[] values = propertyValues.getAll();
for (int i = 0; i < values.length; i++) {
   PropertyValue propertyValue = values[i];
   ............
}

PropertyValues propertyValues = service.getPropertyValues(evidence, Constants.DEVICE, "http://morfeo-project.org/mymobileweb");
PropertyValue[] values = propertyValues.getAll();
for (int i = 0; i < values.length; i++) {
   PropertyValue propertyValue = values[i];
   ............
}

Return the Values of a Specific List

  • Return values for all the supplied Properties, returning empty values for those that are not known. An "unknown value" is distinguished by the PropertyValue exists() method returning false. 
PropertyValues propertyValues = getPropertyValues(evidence, propertyRefs);
PropertyValue[] values = propertyValues.getAll();
for (int i = 0; i < values .length; i++) {
   PropertyValue propertyValue = values[i];
   if (propertyValue.exists()){
      ............
   }
}

PropertyValues propertyValues = getPropertyValues(evidence, propertyRefs);
PropertyValue value = propertyValues.getValues(propertyRef);
if (propertyValue.exists()){
    ............
}

Return the Value of a Single Property

  • Return the value of a specific Property 
PropertyName propertyName = service.newPropertyName("vendor", "http://www.w3.org/2008/01/ddr-core-vocabulary")
PropertyRef propertyRef = service.newPropertyRef(propertyName , Constants.DEVICE)
PropertyValue propertyValue = service.getPropertyValue(evidence, propertyRef);
if (propertyValue.exists()){
   System.out.println("The vendor is " + propertyValue.getString());
}
  • Return the value of a specific Property in its Default Aspect in the Vocabulary specified by propertyName 
PropertyName propertyName = service.newPropertyName("accesskeySupport", "http://morfeo-project.org/mymobileweb")
PropertyValue propertyValue = service.getPropertyValue(evidence, propertyName);
if (propertyValue.getBoolean()){
   System.out.println("Supports accesskey");
}
  • Return the value of a specific Property in its Default Aspect in the Default Vocabulary 
PropertyValue propertyValue = service.getPropertyValue(evidence, "imageFormatSupport");
String[] values= propertyValue.getEnumeration();
System.out.print("[");
int size = values.length;
for (int j = 0; j < size; j++) {
   System.out.print(values[j]);
   if (j < size - 1)
      System.out.print(", ");
}
System.out.print("]");
  • Return the value of a specific Property with a specific Aspect in a specific Vocabulary 
PropertyValue propertyValue = service.getPropertyValue(evidence, "maximumVideoWidth", Constants.DEVICE, "http://morfeo-project.org/mymobileweb");
int width = propertyValue.getInteger();
System.out.println("The maximum video width is " + width );

Returns boolean value according to device belongs to a group 

boolean isIPhone = ((ServiceImpl) service).belongsTo(evidence, "iPhone");
if (isIPhone){
   // Do somethind..
} else {
   // Other..
}

Information Methods

List Available Properties

  • List Properties
    • Lists the combination of all known Properties and Aspects in all Vocabularies that can be used without causing a NameException to be thrown. The order in which Properties are listed is not significant. 
PropertyRef[] propertyRefs = service.listPropertyRefs();

How to extend

Add new vocabulary (based on predefined Services)

It is flexible enough to incorporate other vocabulary.

  • The new vocabulary is called http://www.example.org.
  • This vocabulary knows the device aspect and a property called manufacturer.

The steps:

1. Create the vocabulary descriptor.

example-description.xml 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE VocabularyDescription SYSTEM "vocabulary-description.dtd" [    	
    <!ENTITY DEVICE "device">   
]>

<VocabularyDescription target="http://www.example.org">
   <Aspects>
      <Aspect name="&DEVICE;" />
   </Aspects>

   <Properties>   
      <Property name="manufacturer" datatype="xs:string" aspects="&DEVICE;" defaultAspect="&DEVICE;" />
   </Properties>
</VocabularyDescription>

2. Create the vocabulary mappings.

vocabulary-example-wurfl-mapping.xml 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE VocabularyMappings SYSTEM "vocabulary-mapping.dtd"[    	
    <!ENTITY DEVICE "device">
]>

<VocabularyMappings source="WURFL" target="http://www.example.org">
	
   <TargetProperty name="manufacturer">
      <Match aspect="&DEVICE;">
         <SourceProperty name="brand_name" datatype="xs:string" />
      </Match>
   </TargetProperty>

</VocabularyMappings>

vocabulary-example-uaprof-mapping.xml 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE VocabularyMappings SYSTEM "vocabulary-mapping.dtd"[    	
    <!ENTITY DEVICE "device">
]>

<VocabularyMappings source="UAPROF" target="http://www.example.org">
	
   <TargetProperty name="manufacturer">
      <Match aspect="&DEVICE;">
         <SourceProperty name="Vendor" datatype="xs:string" />
      </Match>
   </TargetProperty>

</VocabularyMappings>

3. Create the vocabulary source.

example-sources.xml 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE VocabularySources SYSTEM "vocabulary-sources.dtd"[    	
    <!ENTITY DEVICE "device">
]>

<VocabularySources target="http://www.example.org">

   <Mappings>
      <TargetProperty name="manufacturer">
         <Match aspect="&DEVICE;">
	    <PropertySource name="WURFL" priority="1" />
            <PropertySource name="UAPROF" priority="2" />
	 </Match>
      </TargetProperty>
   </Mappings>

</VocabularySources>

Add new vocabulary and Service (instantiating the ServiceImpl)

It is flexible enough to incorporate other services. The user manual supposes that author needs to add a Service called user which supports the vocabulary http://example.org/vocabulary.

The steps:

1. Create the vocabulary descriptor.

user-vocabulary-description.xml 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE VocabularyDescription SYSTEM "vocabulary-description.dtd" [    	
    <!ENTITY DELIVERYCONTEXT "deliveryContext">   
]>

<VocabularyDescription target="http://example.org/vocabulary">
   <Aspects>
      <Aspect name="&DELIVERYCONTEXT;" />
   </Aspects>

   <Properties>   
      <Property name="carrier" datatype="xs:string" aspects="&DELIVERYCONTEXT;" defaultAspect="&DELIVERYCONTEXT;" />
   </Properties>
</VocabularyDescription>

2. Create the vocabulary mappings.

vocabulary-user-user-mapping.xml 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE VocabularyMappings SYSTEM "vocabulary-mapping.dtd"[    	
    <!ENTITY DELIVERYCONTEXT "deliveryContext">   
]>

<VocabularyMappings source="user" target="http://example.org/vocabulary">

   <TargetProperty name="carrier">
	<Match aspect="&DELIVERYCONTEXT;">
	      <SourceProperty name="carrier" datatype="xs:string" />
	</Match>
   </TargetProperty>

</VocabularyMappings>


3. Add the source mapping for the new vocabulary.

user-sources.xml 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE VocabularySources SYSTEM "vocabulary-sources.dtd"[    	
    <!ENTITY DELIVERYCONTEXT "deliveryContext">   
]>

<VocabularySources target="http://example.org/vocabulary">

    <!-- Mappings -->
    <Mappings>
        <TargetProperty name="carrier">
	     <Match aspect="&DELIVERYCONTEXT;">
		<PropertySource name="user" priority="1" />
  	     </Match>
	</TargetProperty>
    </Mappings>

</VocabularySources>

4. Add new data source.

sources.xml 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE Sources SYSTEM "sources.dtd"[    	
    <!ENTITY DELIVERYCONTEXT "deliveryContext">   
]>

<Sources>

    <Sources>
        <!-- New Source -->
	<Source name="user" class="my.example.UserService" />		
        <Source name="WURFL" class="org.morfeo.devinfo.simple.WURFLService" />
	<Source name="UAPROF" class="org.morfeo.devinfo.simple.UAProfService" />	
    </Sources>

</Sources>

5. Create the my.example.UserService class extends org.morfeo.devinfo.simple.ServiceAbstract.

Example: UserService.java 

public class UserService extends ServiceAbstract {

   public void initialize(String defaultVocabularyIRI, Properties props)
			throws InitializationException, NameException {
      super.initialize(defaultVocabularyIRI, props);
   }

   @Override
   public PropertyValue getPropertyValue(Evidence evidence,
      	                PropertyRef propertyRef) throws NameException {

      if (evidence == null || propertyRef == null) {
         String message = MessagesManager.getMessage(MessagesManager.NULL_ARG);
 	 log.error(message);
	 throw new SystemException(SystemException.ILLEGAL_ARGUMENT, message);
      }

      // Validating propertyRef parameter...
      PropertyRef propertyRefOK = newPropertyRef(newPropertyName(propertyRef.getLocalPropertyName(),
                  propertyRef.getNamespace()),propertyRef.getAspectName());

      // New empty PropertyValue
      PropertyValue ret = new PropertyValueImpl(propertyRefOK, null);

      // Retrieving TargetProperty
      TargetProperty targetProperty = vocabularyMappingsManager.getProperty("user", 
                     propertyRefOK.getNamespace(), propertyRefOK.getLocalPropertyName());

      // TargetProperty not null and has mapping...
      if (targetProperty != null && targetProperty.hasMappings()) {

         // Retrieving SourceProperty.
         SourceProperty sourceProperty = targetProperty.getSourceProperty(propertyRef.getAspectName());

         if (sourceProperty != null) {
	    // carrier in this example
  	    String name = sourceProperty.getPropertyName();
	
            // Calculating...
	    Object value = getValue(name);
	
            // Returns new Property Value
	    ret = new PropertyValueImpl(propertyRef, value);
         }
      }

      return ret;
   }

   @Override
   public PropertyValues getPropertyValues(Evidence evidence,
			PropertyRef[] propertyRefs) throws NameException {
      // Creating the PropertyValues ...
   }

   private Object getValue(String sourceProperty) {
      Object ret = null;
      // Do something...
      return ret;
   }

}

Add new vocabulary and Service (instantiating your Service)

1. Create the vocabulary descriptor.

user-vocabulary-description.xml 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE VocabularyDescription SYSTEM "vocabulary-description.dtd" [    	
    <!ENTITY DELIVERYCONTEXT "deliveryContext">   
]>

<VocabularyDescription target="http://example.org/vocabulary">
   <Aspects>
      <Aspect name="&DELIVERYCONTEXT;" />
   </Aspects>

   <Properties>   
      <Property name="carrier" datatype="xs:string" aspects="&DELIVERYCONTEXT;" defaultAspect="&DELIVERYCONTEXT;" />
   </Properties>
</VocabularyDescription>

2. Create the my.example.UserService class extends org.morfeo.devinfo.simple.ServiceAbstract.

Example: UserService.java 

public class UserService extends ServiceAbstract {

   public void initialize(String defaultVocabularyIRI, Properties props)
			throws InitializationException, NameException {
      super.initialize(defaultVocabularyIRI, props);
   }

   @Override
   public PropertyValue getPropertyValue(Evidence evidence,
      	                PropertyRef propertyRef) throws NameException {
      return null;
   }

   @Override
   public PropertyValues getPropertyValues(Evidence evidence,
			PropertyRef[] propertyRefs) throws NameException {
      return null;
   }

}

Feedback

Should you have any comment or feedback, please contact us at:

Retrieved from "http://forge.morfeo-project.org/wiki_en/index.php/DDR-RI_User_Manual"