de.smartics.properties.tutorial.property
Class PropertyTutorial

java.lang.Object
  de.smartics.properties.tutorial.property.PropertyTutorial

@Document(title="What is a Property?",
          sortKey="basics0030")
@DocCategory(value="basics")
public class PropertyTutorial
     
     

      
      extends 
      
      Object
     
     

This tutorial introduces the elements of a property and gives examples on how properties are declared.

Constructor Summary

PropertyTutorial()

Method Summary

void	accessingAPropertyValue() There is also nothing special about accessing the property and it works exactly as shown in OneStringPropertyTutorial .
void	accessingPropertyDocumentMetaData() Document meta data allows a documentation on a property to be inserted into the context of a project documentation.
void	declarationOfAProperty() The declaration states the purpose of a property.
void	definitionOfAPropertyValue() There is nothing new here according to the configuration shown in OneStringPropertyTutorial .
void	noPropertiesFile() If the properties file to define the properties (associate the declarations with property values) cannot be found, the following exception is thrown:
void	omittingTheNameOfThePropertySet() If the name of the property set is not mentioned as a prefix to the name of the property, the property cannot be found.
void	setUp()
void	troubleShooting() You may encounter on of the following problems.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PropertyTutorial

public PropertyTutorial()

Method Detail

setUp

public void setUp()

declarationOfAProperty

@DocChapter
public void declarationOfAProperty()

The declaration states the purpose of a property. All meta data about the property is specified. Everything to be known about the property, besides its actual value, is fixed with its declaration. The information of the declaration is stored with a property descriptor.

We saw the declaration of a property in OneStringPropertyTutorial . A simple property of type String has been declared. We can request a method to access the property descriptor of that property by adding a method that returns an instance of PropertyDescriptor.

Besides the method hostPropertyDescriptor() to access the property descriptor, this example also shows real comments - in form of Javadoc. Let's have a look how the information stored in a property descriptor is accessed.

At we access the data type of the property: It is a String in this case since the return type is declared as such. Second, we see that we can access the documentation in form of a comment. This is the text that is given as Javadoc comment given to the property method.

At we have access to the property set name and property key, which turns out to be tutorial.property (as given with the @PropertiesSet annotation) and host. This information can be accessed individually without retrieving the property descriptor. For more information on this topic please refer to .

At we see that there is no expression that constructs a default value if no explicit value is given. There are no constraints a property value has to meet. Please refer to the tutorials on expressions and constraints for more information on those topics.

At we see that properties are per default read-only. Consequently the update time is set to NO_AUTOMATIC_UPDATE. The time the property is set is at startup (please refer to PropertyDefinitionTime for a list of valid configuration times. The tutorial on deployment provides more information about these properties.

At there is access to properties meta data. This information allows to add meta data commonly used with documents, such as tags or categories. We have a look at all the values in the next section.

accessingPropertyDocumentMetaData

@DocSection
public void accessingPropertyDocumentMetaData()

Document meta data allows a documentation on a property to be inserted into the context of a project documentation. They allow to categorize or tag a document, insert them in a hierarchy by specifying one or more parent documents, provide information about the intended audience.

The author of a property may also add notes, short and summary descriptions, a title and a sort key.

To uniquely identify a document the author may specify a name that is unique within a given space (there are no unique constraint on the title).

What you have seen in the code snippet is the default if none of this information has been specified. All information besides title, space and name are null or empty. For an example to add such information, please refer to PropertyMetaDataTutorial for detailed information.

definitionOfAPropertyValue

@DocChapter
public void definitionOfAPropertyValue()

There is nothing new here according to the configuration shown in OneStringPropertyTutorial . We still use a configuration that selects property definitions in form of properties files on the classpath. Again: The location of the properties file is the same as the location of the interface that declares the property set.

In this example you see the definition of one String and one URL property.

accessingAPropertyValue

@DocChapter
public void accessingAPropertyValue()
                             throws MalformedURLException

There is also nothing special about accessing the property and it works exactly as shown in OneStringPropertyTutorial . Here we show that some property types (e.g. URL) are automatically converted.

Throws:

MalformedURLException

troubleShooting

@DocChapter
public void troubleShooting()

You may encounter on of the following problems.

noPropertiesFile

@DocSection
public void noPropertiesFile()

If the properties file to define the properties (associate the declarations with property values) cannot be found, the following exception is thrown:

 de.smartics.properties.api.config.domain.ConfigurationNotFoundException: Configuration '<no named key>' cannot be loaded from: ApplicationProperties.properties
   at de.smartics.properties.spi.config.support.AbstractInMemoryConfigurationProperties.loadDefault(AbstractInMemoryConfigurationProperties.java:166)
   at de.smartics.properties.spi.config.support.AbstractInMemoryConfigurationProperties.addClassPathProperties(AbstractInMemoryConfigurationProperties.java:148)
   at de.smartics.properties.tutorial.property.metadata.PropertyMetaDataTutorial.createConfiguration(PropertyMetaDataTutorial.java:60)
   at de.smartics.properties.tutorial.property.metadata.PropertyMetaDataTutorial.setUp(PropertyMetaDataTutorial.java:51)
   at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
   at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39)
   at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:25)
   at java.lang.reflect.Method.invoke(Method.java:597)
   at org.junit.runners.model.FrameworkMethod$1.runReflectiveCall(FrameworkMethod.java:45)
   at org.junit.internal.runners.model.ReflectiveCallable.run(ReflectiveCallable.java:15)
   at org.junit.runners.model.FrameworkMethod.invokeExplosively(FrameworkMethod.java:42)
   at org.junit.internal.runners.statements.RunBefores.evaluate(RunBefores.java:27)
   at org.junit.runners.ParentRunner.runLeaf(ParentRunner.java:263)
   at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:68)
   at org.junit.runners.BlockJUnit4ClassRunner.runChild(BlockJUnit4ClassRunner.java:47)
   at org.junit.runners.ParentRunner$3.run(ParentRunner.java:231)
   at org.junit.runners.ParentRunner$1.schedule(ParentRunner.java:60)
   at org.junit.runners.ParentRunner.runChildren(ParentRunner.java:229)
   at org.junit.runners.ParentRunner.access$000(ParentRunner.java:50)
   at org.junit.runners.ParentRunner$2.evaluate(ParentRunner.java:222)
   at org.junit.runners.ParentRunner.run(ParentRunner.java:300)
   at org.eclipse.jdt.internal.junit4.runner.JUnit4TestReference.run(JUnit4TestReference.java:50)
   at org.eclipse.jdt.internal.junit.runner.TestExecution.run(TestExecution.java:38)
   at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:467)
   at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.runTests(RemoteTestRunner.java:683)
   at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.run(RemoteTestRunner.java:390)
   at org.eclipse.jdt.internal.junit.runner.RemoteTestRunner.main(RemoteTestRunner.java:197)
 

If a configuration is not found, the source for property values are not found. In our case we read the property values from the class path in form of a properties file. It depends on the configuration implementation where the property values have to be placed. In our case the requested location of ApplicationProperties.properties is the same classpath location as the ApplicationProperties interface.

omittingTheNameOfThePropertySet

@DocSection
public void omittingTheNameOfThePropertySet()

If the name of the property set is not mentioned as a prefix to the name of the property, the property cannot be found.

In this case the property is not mandatory and therefore the value for this property is simply null.