-
Notifications
You must be signed in to change notification settings - Fork 2
Developer Guidelines
- Contributor guidelines
- Building deegree
- Test Practices
- What to do when fixing a bug or implementing a feature?
Contributors should use the official conventions for formatting source code. You can download the offical deegree formatter settings for Eclipse here: https://raw.github.com/wiki/deegree/deegree3/formatter.xml
Note that you can automatically apply the formatter settings to your Eclipe workspace, by using the deegree maven plugin. See https://github.com/deegree/deegree-maven-plugin/wiki/EclipseMojo or https://github.com/deegree/deegree-maven-plugin/wiki/EclipseProjectLinkerMojo.
This is the header to use for new java files. Download https://raw.github.com/wiki/deegree/deegree3/codetemplates.xml for easy Eclipse import (includes class headers).
See it here:
/*----------------------------------------------------------------------------
This file is part of deegree
Copyright (C) 2001-2015 by:
- Department of Geography, University of Bonn -
and
- lat/lon GmbH -
and others
This library is free software; you can redistribute it and/or modify it under
the terms of the GNU Lesser General Public License as published by the Free
Software Foundation; either version 2.1 of the License, or (at your option)
any later version.
This library is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
details.
You should have received a copy of the GNU Lesser General Public License
along with this library; if not, write to the Free Software Foundation, Inc.,
59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Contact information:
e-mail: info@deegree.org
website: http://www.deegree.org/
----------------------------------------------------------------------------*/This is the template to be used for class javadocs.
Download https://raw.github.com/wiki/deegree/deegree3/codetemplates.xml for easy eclipse import (includes the file headers).
See an example here:
/**
* This class is responsible for these things.
*
* @author <a href="mailto:john.doe@acme.com">John Doe</a>
*
* @since 3.4
*/As a starting point read the following post which gives an overview of dos and don'ts: https://nobugsproject.com/2017/05/28/11-mistakes-java-developers-make-when-using-exceptions/
In deegree 3, we're usually using log4j for logging (through slf4j). It is generally a nice thing to have a 'template' log4j.properties, where the important classes are listed together with a description what is logged on which level, like this:
# logs very important information
#log4j.logger.org.deegree.services.wms.MostImportantClass=TRACE
# logs the most important information
#log4j.logger.org.deegree.services.wms.MostImportantClass=DEBUG
This information is now generated automatically using annotations. You can annotate a class using the LoggingNotes annotation, like this:
@LoggingNotes(debug = "logs the most important information", trace = "logs very important information")
public class MostImportantClass {
...
You can optionally set the text for warn, info, error, debug and trace, corresponding to the log level of the same name. The above annotation will generate exactly the log4j.properties snippet as shown (speling mistakes which I integrated are excluded).
For packages, we have the PackageLoggingNotes. These can be used to generate a section header, and to generate package level descriptions as shown above. So additionally, you have the (optional) title parameter for the annotation. To make a package level annotation, create a new package-info.java file in your package, with content like this:
@PackageLoggingNotes(title = "the WMS section", debug = "logs debugging stuff", warn = "logs possible problems")
package org.deegree.services.wms;
To generate a useful log4j.properties template, you'll have to check out d3_core and d3_services. Edit the build.properties as appropriate, and run the ant target make-log4j.properties in d3_services. This will give you a proper log4j.properties in d3_services/build/.
XMLStreamReader and XMLStreamWriter are used heavily in deegree 3 for processing streams of XML. Special care has to be taken in order to use XMLStreamWriter in a way that is compatible with different StaX implementations (e.g. bundled versions with JDK, Woodstox, StaX implementation on Oracle Weblogic). Problems occur when dealing with qualified element/attribute names and binding namespaces.
Best practices:
- See http://ws.apache.org/axiom/devguide/ch03.html for more info on established usage patterns for XMLStreamWriter. All deegree code should follow usage pattern 3.
- Don't set javax.xml.stream.isRepairingNamespaces to true when creating the XMLStreamWriter. It may look like a good idea for easing the task of binding namespaces and catching unbound namespaces, but it turned out that the introduced behaviour differs between different StaX-implementations and it is makes it hard to detect possible errors. Without it, you have to call XMLStreamWriter.writeNamespace(String prefix, String uri) manually, but at least a dependable behavior is achieved among implementations.
- Understand that (in non-repairing mode) XMLStreamWriter.setPrefix(String prefix, String uri) only makes a namespace binding known to the XMLStreamWriter instance, but does not actually write xmlns:prefix="namespace" to the stream. XMLStreamWriter.writeNamespace(String prefix, String uri) writes xmlns:prefix="namespace" to the stream (and makes the binding known as well).
- Using XMLStreamWriter.write (String namespaceURI, String localName) should be preferred over XMLStreamWriter.write (String prefix, String localName, String namespaceURI), as it eases the task of changing the prefix (and avoids redundancy in general). Only use XMLStreamWriter.write (String prefix,String localName,String namespaceURI) in case an element needs to be written that has a namespace that may be unbound at this point.
- There's a special issue with writeEmptyElement(...). The problem is that the local bindings for this element are kept after the empty element has been written. Apparently, StaX must do so in order to allow writing of (qualified) attributes. In order to make the namespace context forget the local bindings, writer.writeCharacters( "" ); seems to do the trick.