Bug 551438 - Fix files that have ended up with CRLF in the git
repository
Change-Id: I5f80ae6115b93f0c97012415586a093d69ec1ba2
Signed-off-by: Ed Merks <ed.merks@gmail.com>
diff --git a/bundles/org.eclipse.jdt.doc.isv/guide/jdt_api_searchindex.htm b/bundles/org.eclipse.jdt.doc.isv/guide/jdt_api_searchindex.htm
index 4128afc..d20e35b 100644
--- a/bundles/org.eclipse.jdt.doc.isv/guide/jdt_api_searchindex.htm
+++ b/bundles/org.eclipse.jdt.doc.isv/guide/jdt_api_searchindex.htm
@@ -1,41 +1,41 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
-<head>
-<meta name="copyright" content=
-"Copyright (c) IBM Corporation and others 2012. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." />
-<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta http-equiv="Content-Style-Type" content="text/css" />
-<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css" />
-<title>Setting the Java build path</title>
-<link rel="stylesheet" type="text/css" href="../book.css" />
-</head>
-<body>
-<h2>Indexes for the Java search</h2>
-<p>The JDT search creates indexes for all the sources and the dependent JARs. As a JAR gets added onto the classpath, it is indexed.
-This operation could take some time depending upon the size of the JAR. To improve the performance, one can pre-build the index and specify the index file for a JAR
-when it gets added onto the classpath. This is only supported for JARs.
-</p>
-<h3> Generating the index </h3>
-<p> An index can be pre-generated in the following ways:</p>
-<ul>
- <li> An API <b><a href=
- "../reference/api/org/eclipse/jdt/core/index/JavaIndexer.html#generateIndexForJar(String,%20String)">
- JavaIndexer#generateIndexForJar</a></b>.
- </li>
- <li> A command line application <b><a href=
- "../reference/api/org/eclipse/jdt/core/index/JavaIndexerApplication.html">
- JavaIndexer</a></b>
- </li>
- <li> An Ant task <b><a href= "../reference/api/org/eclipse/jdt/core/BuildJarIndex.html">
- eclipse.buildJarIndex</a></b>
- </li>
-</ul>
-
-<h3> Specifying the index </h3>
-<p> The index can be specified as a <b><a href="../reference/api/org/eclipse/jdt/core/IClasspathAttribute.html#INDEX_LOCATION_ATTRIBUTE_NAME">classpath attribute</a></b>
- of the library that is getting added. The index file has to be in a valid URL form. If the index file
- is not found, JDT generates an index file and uses it for searches.
-</p>
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+<head>
+<meta name="copyright" content=
+"Copyright (c) IBM Corporation and others 2012. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." />
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+<meta http-equiv="Content-Style-Type" content="text/css" />
+<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css" />
+<title>Setting the Java build path</title>
+<link rel="stylesheet" type="text/css" href="../book.css" />
+</head>
+<body>
+<h2>Indexes for the Java search</h2>
+<p>The JDT search creates indexes for all the sources and the dependent JARs. As a JAR gets added onto the classpath, it is indexed.
+This operation could take some time depending upon the size of the JAR. To improve the performance, one can pre-build the index and specify the index file for a JAR
+when it gets added onto the classpath. This is only supported for JARs.
+</p>
+<h3> Generating the index </h3>
+<p> An index can be pre-generated in the following ways:</p>
+<ul>
+ <li> An API <b><a href=
+ "../reference/api/org/eclipse/jdt/core/index/JavaIndexer.html#generateIndexForJar(String,%20String)">
+ JavaIndexer#generateIndexForJar</a></b>.
+ </li>
+ <li> A command line application <b><a href=
+ "../reference/api/org/eclipse/jdt/core/index/JavaIndexerApplication.html">
+ JavaIndexer</a></b>
+ </li>
+ <li> An Ant task <b><a href= "../reference/api/org/eclipse/jdt/core/BuildJarIndex.html">
+ eclipse.buildJarIndex</a></b>
+ </li>
+</ul>
+
+<h3> Specifying the index </h3>
+<p> The index can be specified as a <b><a href="../reference/api/org/eclipse/jdt/core/IClasspathAttribute.html#INDEX_LOCATION_ATTRIBUTE_NAME">classpath attribute</a></b>
+ of the library that is getting added. The index file has to be in a valid URL form. If the index file
+ is not found, JDT generates an index file and uses it for searches.
+</p>
+</body>
+</html>
diff --git a/bundles/org.eclipse.jdt.doc.isv/schema.css b/bundles/org.eclipse.jdt.doc.isv/schema.css
index 3a25ba2..ec3c49b 100644
--- a/bundles/org.eclipse.jdt.doc.isv/schema.css
+++ b/bundles/org.eclipse.jdt.doc.isv/schema.css
@@ -1,71 +1,71 @@
-/*******************************************************************************
- * Copyright (c) 2003, 2009 IBM Corporation and others.
- * All rights reserved. This program and the accompanying materials
- * are made available under the terms of the Eclipse Public License v1.0
- * which accompanies this distribution, and is available at
- * http://www.eclipse.org/legal/epl-v10.html
- *
- * Contributors:
- * IBM Corporation - initial API and implementation
- *******************************************************************************/
-
-H6.SchemaHeader {
- font-size:16px;
- display:inline
-}
-
-P.SchemaCopyright {
- font-size: smaller;
- font-style: normal;
- color: #336699;
- display:inline;
- margin-top: 3.000000pt;
- margin-bottom: 11.000000pt;
- margin-right: 0.000000pt;
- margin-left: 0.000000pt;
-}
-
-P.SchemaDtd {
- color: #800000;
- margin-top: 0.000000pt;
- margin-bottom: 0.000000pt;
- margin-right: 0.000000pt;
- margin-left: 10.000000pt;
-}
-
-P.SchemaDtdAttlist {
- color: #800000;
- margin-top: 0.000000pt;
- margin-bottom: 0.000000pt;
- margin-right: 0.000000pt;
- margin-left: 20.000000pt;
-}
-
-span.SchemaTag {
- color: #000080;
-}
-
-span.SchemaCstring {
- color: #008000;
-}
-
-pre.Example {
- margin-top: 0.000000pt;
-}
-
-.ConfigMarkupElementDesc {
- color: black;
- margin-top: 0.000000pt;
- margin-bottom: 0.000000pt;
- margin-right: 0.000000pt;
- margin-left: 10.000000pt;
-}
-
-.ConfigMarkupAttlistDesc {
- color: black;
- margin-top: 0.000000pt;
- margin-bottom: 0.000000pt;
- margin-right: 0.000000pt;
- margin-left: 32.000000pt;
-}
-
+/*******************************************************************************
+ * Copyright (c) 2003, 2009 IBM Corporation and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ * IBM Corporation - initial API and implementation
+ *******************************************************************************/
+
+H6.SchemaHeader {
+ font-size:16px;
+ display:inline
+}
+
+P.SchemaCopyright {
+ font-size: smaller;
+ font-style: normal;
+ color: #336699;
+ display:inline;
+ margin-top: 3.000000pt;
+ margin-bottom: 11.000000pt;
+ margin-right: 0.000000pt;
+ margin-left: 0.000000pt;
+}
+
+P.SchemaDtd {
+ color: #800000;
+ margin-top: 0.000000pt;
+ margin-bottom: 0.000000pt;
+ margin-right: 0.000000pt;
+ margin-left: 10.000000pt;
+}
+
+P.SchemaDtdAttlist {
+ color: #800000;
+ margin-top: 0.000000pt;
+ margin-bottom: 0.000000pt;
+ margin-right: 0.000000pt;
+ margin-left: 20.000000pt;
+}
+
+span.SchemaTag {
+ color: #000080;
+}
+
+span.SchemaCstring {
+ color: #008000;
+}
+
+pre.Example {
+ margin-top: 0.000000pt;
+}
+
+.ConfigMarkupElementDesc {
+ color: black;
+ margin-top: 0.000000pt;
+ margin-bottom: 0.000000pt;
+ margin-right: 0.000000pt;
+ margin-left: 10.000000pt;
+}
+
+.ConfigMarkupAttlistDesc {
+ color: black;
+ margin-top: 0.000000pt;
+ margin-bottom: 0.000000pt;
+ margin-right: 0.000000pt;
+ margin-left: 32.000000pt;
+}
+
diff --git a/bundles/org.eclipse.jdt.doc.user/tasks/task-avoiding_resource_leaks.htm b/bundles/org.eclipse.jdt.doc.user/tasks/task-avoiding_resource_leaks.htm
index 432d014..32d74a3 100644
--- a/bundles/org.eclipse.jdt.doc.user/tasks/task-avoiding_resource_leaks.htm
+++ b/bundles/org.eclipse.jdt.doc.user/tasks/task-avoiding_resource_leaks.htm
@@ -1,88 +1,88 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html lang="en">
-<head>
-<meta name="copyright" content="Copyright (c) GK Software AG and others 2012. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<meta http-equiv="Content-Style-Type" content="text/css">
-<link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type="text/css">
-<title>Avoiding resource leaks</title>
-</head>
-<body>
-<h1> Avoiding resource leaks </h1>
-<p>
-Classes implementing the interface <code>java.io.Closeable</code> (since JDK 1.5) and
-<code>java.lang.AutoCloseable</code> (since JDK 1.7) are considered to represent external
-resources, which should be closed using method <code>close()</code>, when they are
-no longer needed.
-</p>
-<p>
-The Eclipse Java compiler is able to analyze whether code using such types adheres
-to this policy. E.g., the following snippet represents an obvious resource leak:
-</p>
-<pre> int len(File f) throws IOException {
- InputStream stream = new FileInputStream(f);
- return stream.available();
- }
-</pre>
-<p>
-The compiler will flag this with <b>"Resource leak: 'stream' is never closed".</b>
-<h2>Basic flow analysis for resource leaks</h2>
-<p>
-Flow analysis detects the following situations:
-</p>
-<ul>
-<li>A resource is definitely not closed</li>
-<li>A resource is not closed on all control flows (flagged as "may not be closed")</li>
-<li>A resource is not closed at a method exit point (return statement or when an exception is raised) (definitely or on some control flow)</li>
-<li>In a Java 7 program a resource is closed but the code could still be improved by using a try-with-resources statement.</li>
-</ul>
-<p>
-Additionally, flow analysis tries to follow resource values through variable assignments.
-However, if different resources may be assigned to the same variable (on different control flows or in sequence),
-the analysis can become less accurate.
-</p>
-<p>Not all the analysis is enabled by default. Please consult the <a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#resource-leak">compiler preferences</a>
-regarding the individual configuration options.
-</p>
-<p><strong>Hints:</strong> Code will generally be easier to analyze (and easier to understand by human readers)
-if resource-type variables are not reused for different purposes.
-Ideally, in Java 7 programs all resources should be managed with a try-with-resources statement.
-</p>
-<h2>Ownership / responsibility</h2>
-<p>
-The above diagnostics basically assume that a method that creates an instance of a resource type
-is also responsible for closing this resource.
-However, some resources will be shared among several methods. Here the analysis makes the following assumptions:
-</p>
-<ul>
-<li>If a method returns a resource to its caller, it is not responsible for closing; no problem is reported.</li>
-<li>If a resource is stored in a field, no single method is considered as responsible for closing; no problem is reported.</li>
-<li>If a method obtains a resource via a method call rather than by a <code>new</code> expression, it may or may not
- be responsible; any problems are only flagged as potential resource leaks.</li>
-<li>If a resource is passed as an argument in a method call or constructor call, the current method
-may or may not be responsible; any problems are only flagged as potential resource leaks.</li>
-</ul>
-<h2>Resource wrappers and resource-free closeables</h2>
-<p>
-The JDK defines a few classes which implement <code>Closeable</code> but do not directly represent
-a resource at the level of the operating system.
-</p>
-<p><code>java.io.StringReader</code> is an example of a closeable that doesn't require calling <code>close()</code>
-because <b>no operating system resources</b> are held that would require clean-up.
-The analysis uses an explicit white list to detect classes from <code>java.io</code> that fall in this category.
-No resource leak warnings are issued regarding these classes.
-</p>
-<p>Instances of classes like <code>java.io.BufferedInputStream</code> are <b>wrappers</b> around another resource
-(where wrappers can be applied at multiple levels).
-Also these objects do not directly represent an operating system resource.
-If the wrapped resource is closed, the wrapper doesn't need closing.
-Conversely, if a wrapper is closed this will include closing of the wrapped resource.
-The analysis has a second white list for detecting wrapper resources, and will recognize whether
-the underlying actual resource will be closed directly or indirectly via the wrapper.
-Either one suffices to silence warnings regarding resource leaks.
-The white list contains classes from <code>java.io</code>, <code>java.util.zip</code>, <code>java.security</code>, <code>java.beans</code>
-and <code>java.sound.sampled</code>.
-</p>
-<p><strong>Hint:</strong> It is generally preferable/safest to close the outermost wrapper, not a wrapped resource.
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+<head>
+<meta name="copyright" content="Copyright (c) GK Software AG and others 2012. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type="text/css">
+<title>Avoiding resource leaks</title>
+</head>
+<body>
+<h1> Avoiding resource leaks </h1>
+<p>
+Classes implementing the interface <code>java.io.Closeable</code> (since JDK 1.5) and
+<code>java.lang.AutoCloseable</code> (since JDK 1.7) are considered to represent external
+resources, which should be closed using method <code>close()</code>, when they are
+no longer needed.
+</p>
+<p>
+The Eclipse Java compiler is able to analyze whether code using such types adheres
+to this policy. E.g., the following snippet represents an obvious resource leak:
+</p>
+<pre> int len(File f) throws IOException {
+ InputStream stream = new FileInputStream(f);
+ return stream.available();
+ }
+</pre>
+<p>
+The compiler will flag this with <b>"Resource leak: 'stream' is never closed".</b>
+<h2>Basic flow analysis for resource leaks</h2>
+<p>
+Flow analysis detects the following situations:
+</p>
+<ul>
+<li>A resource is definitely not closed</li>
+<li>A resource is not closed on all control flows (flagged as "may not be closed")</li>
+<li>A resource is not closed at a method exit point (return statement or when an exception is raised) (definitely or on some control flow)</li>
+<li>In a Java 7 program a resource is closed but the code could still be improved by using a try-with-resources statement.</li>
+</ul>
+<p>
+Additionally, flow analysis tries to follow resource values through variable assignments.
+However, if different resources may be assigned to the same variable (on different control flows or in sequence),
+the analysis can become less accurate.
+</p>
+<p>Not all the analysis is enabled by default. Please consult the <a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#resource-leak">compiler preferences</a>
+regarding the individual configuration options.
+</p>
+<p><strong>Hints:</strong> Code will generally be easier to analyze (and easier to understand by human readers)
+if resource-type variables are not reused for different purposes.
+Ideally, in Java 7 programs all resources should be managed with a try-with-resources statement.
+</p>
+<h2>Ownership / responsibility</h2>
+<p>
+The above diagnostics basically assume that a method that creates an instance of a resource type
+is also responsible for closing this resource.
+However, some resources will be shared among several methods. Here the analysis makes the following assumptions:
+</p>
+<ul>
+<li>If a method returns a resource to its caller, it is not responsible for closing; no problem is reported.</li>
+<li>If a resource is stored in a field, no single method is considered as responsible for closing; no problem is reported.</li>
+<li>If a method obtains a resource via a method call rather than by a <code>new</code> expression, it may or may not
+ be responsible; any problems are only flagged as potential resource leaks.</li>
+<li>If a resource is passed as an argument in a method call or constructor call, the current method
+may or may not be responsible; any problems are only flagged as potential resource leaks.</li>
+</ul>
+<h2>Resource wrappers and resource-free closeables</h2>
+<p>
+The JDK defines a few classes which implement <code>Closeable</code> but do not directly represent
+a resource at the level of the operating system.
+</p>
+<p><code>java.io.StringReader</code> is an example of a closeable that doesn't require calling <code>close()</code>
+because <b>no operating system resources</b> are held that would require clean-up.
+The analysis uses an explicit white list to detect classes from <code>java.io</code> that fall in this category.
+No resource leak warnings are issued regarding these classes.
+</p>
+<p>Instances of classes like <code>java.io.BufferedInputStream</code> are <b>wrappers</b> around another resource
+(where wrappers can be applied at multiple levels).
+Also these objects do not directly represent an operating system resource.
+If the wrapped resource is closed, the wrapper doesn't need closing.
+Conversely, if a wrapper is closed this will include closing of the wrapped resource.
+The analysis has a second white list for detecting wrapper resources, and will recognize whether
+the underlying actual resource will be closed directly or indirectly via the wrapper.
+Either one suffices to silence warnings regarding resource leaks.
+The white list contains classes from <code>java.io</code>, <code>java.util.zip</code>, <code>java.security</code>, <code>java.beans</code>
+and <code>java.sound.sampled</code>.
+</p>
+<p><strong>Hint:</strong> It is generally preferable/safest to close the outermost wrapper, not a wrapped resource.
+</body>
+</html>
diff --git a/bundles/org.eclipse.jdt.doc.user/tasks/task-improve_code_quality.htm b/bundles/org.eclipse.jdt.doc.user/tasks/task-improve_code_quality.htm
index 603bc12..5482e19 100644
--- a/bundles/org.eclipse.jdt.doc.user/tasks/task-improve_code_quality.htm
+++ b/bundles/org.eclipse.jdt.doc.user/tasks/task-improve_code_quality.htm
@@ -1,36 +1,36 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html lang="en">
-<head>
-<meta name="copyright" content="Copyright (c) GK Software AG and others 2012. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<meta http-equiv="Content-Style-Type" content="text/css">
-<link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type="text/css">
-<title>Improving Java code quality</title>
-</head>
-<body>
-<h1> Improving Java code quality </h1>
-<p>
-The Eclipse Java compiler performs more checks and analyses than are mandated by the Java Language Specification.
-This is done in order to help you to improve the quality of your Java code.
-Since different users have different views of which warnings are interesting, this behavior is highly configurable.
-See <a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm">Java Compile Errors/Warnings Preferences</a>
-for available options.
-</p>
-<p>
-Some warnings and errors should be obvious and generally valid for everybody.
-In some cases you may want to configure the compiler to match your code style
-and also your quality goals.
-Some analyses are most helpful if you to some degree adjust your code style
-to make it better analyzable by the compiler.
-</p>
-<p>
-The pages listed below give some background on certain analyses and hints
-on how to make the best use of them:
-</p>
-<ul>
-<li><a href="task-using_null_annotations.htm">Using null annotations</a></li>
-<li><a href="task-avoiding_resource_leaks.htm">Avoiding resource leaks</a></li>
-<li><a href="task-ensuring_switch_completeness.htm">Ensuring completeness of <code>switch</code> statements</a></li>
-</ul>
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+<head>
+<meta name="copyright" content="Copyright (c) GK Software AG and others 2012. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type="text/css">
+<title>Improving Java code quality</title>
+</head>
+<body>
+<h1> Improving Java code quality </h1>
+<p>
+The Eclipse Java compiler performs more checks and analyses than are mandated by the Java Language Specification.
+This is done in order to help you to improve the quality of your Java code.
+Since different users have different views of which warnings are interesting, this behavior is highly configurable.
+See <a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm">Java Compile Errors/Warnings Preferences</a>
+for available options.
+</p>
+<p>
+Some warnings and errors should be obvious and generally valid for everybody.
+In some cases you may want to configure the compiler to match your code style
+and also your quality goals.
+Some analyses are most helpful if you to some degree adjust your code style
+to make it better analyzable by the compiler.
+</p>
+<p>
+The pages listed below give some background on certain analyses and hints
+on how to make the best use of them:
+</p>
+<ul>
+<li><a href="task-using_null_annotations.htm">Using null annotations</a></li>
+<li><a href="task-avoiding_resource_leaks.htm">Avoiding resource leaks</a></li>
+<li><a href="task-ensuring_switch_completeness.htm">Ensuring completeness of <code>switch</code> statements</a></li>
+</ul>
+</body>
+</html>
diff --git a/bundles/org.eclipse.jdt.doc.user/tasks/task-using_external_null_annotations.htm b/bundles/org.eclipse.jdt.doc.user/tasks/task-using_external_null_annotations.htm
index ae5ad80..410ce82 100644
--- a/bundles/org.eclipse.jdt.doc.user/tasks/task-using_external_null_annotations.htm
+++ b/bundles/org.eclipse.jdt.doc.user/tasks/task-using_external_null_annotations.htm
@@ -1,168 +1,168 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html lang="en">
-<head>
-<meta name="copyright" content="Copyright (c) GK Software AG and others 2015. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
-<meta http-equiv="Content-Style-Type" content="text/css">
-<link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type="text/css">
-<title>Using external null annotations</title>
-</head>
-<body>
-<h1> Using external null annotations </h1>
-<p>
-<a href="task-using_null_annotations.htm">Null annotations</a>,
-or even better, <a href="task-using_null_type_annotations.htm">null type annotations</a>
-can significantly reduce (ideally: eliminate) the danger of <code>NullPointerException</code>
-thrown at program runtime.
-Unfortunately, the API of many libraries does not yet consistently specify
-where <code>null</code> is allowed and where it isn't.
-This can be a major source of incompleteness in this endeavor.
-In order to fill this gap, starting with Eclipse 4.5 (Mars),
-JDT supports the concept of <em>external annotations</em>,
-which means that null annotations can be specified in separate files – without modifying the original library.
-If you attach such external null annotations to a given library,
-JDT will then consider these annotations for its static null analysis.<br>
-This help page describes
-</p>
-<ul>
-<li><a href="#structure">the structure of external annotations</a></li>
-<li><a href="#configure">configuring a project to use external annotations</a></li>
-<li><a href="#create">interactively creating external annotations</a></li>
-<li><a href="#inspect">inspecting external annotations</a></li>
-<li><a href="#annotation_kind">differences between declaration annotations and type annotations</a></li>
-</ul>
-<h2 id="structure">Structure of external annotations</h2>
-<p>
-External annotations can be provided as a <em>directory tree</em>,
-whose leaves are text files with extension <code>.eea</code> ("Eclipse External Annotations").
-In this structure, each directory corresponds to a Java package,
-and each <code>.eea</code> file corresponds to a Java type (class, interface etc.).
-</p>
-<p>
-Optionally, the above structure can be packed in a single zip file with extension <code>.zip</code>
-or <code>.jar</code>.
-</p>
-<p>
-The exact format of <code>.eea</code> text files has been designed with slight bias towards processing by tools.
-Still, these files are amenable to storing, comparing and merging using any version control system.
-The format is based on <em>signatures</em> as defined in
-<a target="_blank" href="http://docs.oracle.com/javase/specs/jvms/se8/html/jvms-4.html#jvms-4.7.9.1"><img src="../images/external-link-ltr-icon.svg" alt="external link"> JVMS 4.7.9.1</a>.
-<!--
-the full definition is given in TODO: write a page for doc.isv: target audience: developers of converts to/from .eea.
- -->
-</p>
-<h2 id="configure">Configuring a project to use external annotations</h2>
-<blockquote id="caveat-configure"><strong>Caveat:</strong>
- When different projects referring to the same library have different configurations with respect
- to external annotations, the UI support described below (command Annotate and Javadoc hovers)
- can easily get confused: When looking at a given library class, JDT may not know which
- project the user is currently working on, producing unexpected results.
- While hopefully this will be improved in a future version, for the time being users are advised
- to use the same external annotation location for all projects referring to the same library.
- A shared ("common") base project will typically be a good choice for hosting external annotations.
-</blockquote>
-<h3>Java Runtime Environments</h3>
-<p>
-External annotations can be directly attached to each JRE configured in the current workspace.
-For this purpose, please use the <a href="./tasks-JREs.htm">Installed JREs</a>
-preference page and click <b>Edit</b> for details of the selected JRE.
-After selecting one or more Jar files contributed by the given JRE installation,
-click <b>External Annotations</b> to open a new dialog,
-where either a directory or a zip file can be selected as the external annotation location for the selected jar(s).
-</p>
-<p>Alternatively, you may select the properties of a specific JRE bound in the
-<a href="../concepts/concept-build-classpath.htm">Java Build Path</a> of a specific project.
-Please note, that attaching external annotations to individual jars of a JRE <em>always</em> affects the workspace preference,
-even if accessed via the project's build path.
-The only way to define a project-specific location for external annotation location for a JRE is via
-the direct child <b>External annotations:</b> of the top-level node called <b>JRE System Library</b>,
-<em>but note, that project specific locations are not recommended, see the <a href="#caveat-configure">"Caveat"</a> above.</em>
-</p>
-<h3>Other Classpath Containers</h3>
-<p>Depending on the build technology in use, projects may have additional classpath containers like
-<b>Plug-in Dependencies</b> or <b>Maven Dependencies</b>.
-For these containers, the only option currently is
-to specify the external annotation location via each projects build path.
-In this case users are advised to manually ensure that the same location is used
-for all projects of the workspace, <em>see the <a href="#caveat-configure">"Caveat"</a> above.</em>
-</p>
-<h3>Other Libraries</h3>
-<p>For any other libraries (jars) explicitly referenced from the Java Build Path of a project,
-external annotations can be attached separately in the <a href="../reference/ref-properties-build-path.htm#libraries">Libraries</a> page of the project's build path.
-</p>
-<h2 id="create">Creating external annotations</h2>
-<p><u>Pre-requisites:</u>
-External annotations require a library with <a href="../reference/ref-properties-source-attachment.htm">source attachment</a>.
-Additionally, annotation based null analysis must be enabled for the current project,
-an external annotation location must be defined for the library and that location must be a directory (not a zip file) within the workspace.
-</p>
-<p>
-After navigating to the desired class, you may select the type (method parameter or method return type)
-that should be affected by an annotation,
-and invoke the new command <b>Annotate</b> (available via context menu and by default bound to <b>Ctrl-1</b>).
-Similar to quick assists in a Java source code editor,
-this command will offer proposals applicable at the current location.
-For external annotations, the three options are:
-</p>
-<ul>
-<li>Annotate as '@NonNull SomeType'</li>
-<li>Annotate as '@Nullable SomeType'</li>
-<li>Remove nullness annotation from type 'SomeType'</li>
-</ul>
-<p>
-For obvious reasons, exactly 2 of these three proposals are offered at any suitable location.
-Behind the scenes this command will create and/or update an <code>.eea</code> file corresponding to the current class.
-The new annotation will then be respected by the compiler:
-Errors and warnings in an open editor will be updated immediately;
-The <b>Problems</b> view will be updated when affected classes are re-compiled.
-</p>
-<blockquote><b>Be careful:</b>
-When attaching external annotations to a library, keep in mind that you are defining a new contract,
-that will then be used to check your program against.
-The compiler will, however, not check the library, whether it actually conforms to this contract.
-By carelessly marking, e.g., a return type as <code>@NonNull</code> you let the compiler
-advise you to remove null checks against return values from the given method.
-If the library <em>does</em> return null in any situation, this null will hit you unguarded.
-<br>
-Before adding an annotation, make sure it is backed by facts, like, e.g.:
-<ul>
-<li>explicit mention in Javadoc, e.g., when a <code>@return</code> specification says: "... or null when ...".</li>
-<li>an explicit null check of a method parameter, which does not throw an exception (implying that null is accepted → <code>@Nullable</code> parameter)</li>
-<li>uncheck dereference of a method parameter (implying that null is not accepted → <code>@NonNull</code> parameter)
-<li>an explicit <code>null</code> return (implying a <code>@Nullable</code> return type)</li>
-<li>explicitly created return values at each return statement (implying a <code>@NonNull</code> return type).</li>
-</ul>
-</blockquote>
-<h2 id="inspect">Inspecting external annotations</h2>
-<p>The immediate effect of external annotations can be observed via changes in compiler errors / warnings.
-For full transparency, annotated library signatures can be inspected using the <em>Javadoc hover</em>
-or <a href="../reference/views/ref-view-javadoc.htm">Javadoc view</a>.<br>
-<em>Due to an implementation limitation, this feature currently only works for
-<a href="./task-using_null_type_annotations.htm">type annotations</a> (Java 8).</em>
-</p>
-
-<h2 id="annotation_kind">Declaration annotations vs type annotations</h2>
-<p>Generally, support for external annotations has been developed with regard to fully supporting
-all locations of <a href="task-using_null_type_annotations.htm">null type annotations</a> (Java 8).
-This means, you may refer to any detail of a type in a method signature and annotate, e.g., a type parameter, a type bound or an array dimension.
-When using declaration annotations, the relevant subset of location shares the same mechanisms for external annotations.
-</p>
-<p>
-In one situation the design for type annotations shines through even when using declaration annotations:
-annotating an array type is based on the new syntax of type annotations (see also <a href="task-using_null_type_annotations.htm#compatibility_syntax">Compatibility > Syntax</a>).
-For illustration consider the following method in type <code>Collection</code>:
-</p>
-<pre> Object [] toArray();
-</pre>
-<p>
-Even when a project uses Java 7 or below, the return type of this method is annotated by
-placing the cursor before the array brackets.
-Invoking <b>Annotate</b> will create an external annotation that is internally interpreted
-as an annotation on the method (but still the meaning is: describing the return of this method).
-</p>
-<p>
-Other than this one exception, external annotations closely mimic how annotations directly within a source file would be handled,
-with a reduced set of locations for declaration annotations, and the full set of locations for type annotations.
-</p>
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+<head>
+<meta name="copyright" content="Copyright (c) GK Software AG and others 2015. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type="text/css">
+<title>Using external null annotations</title>
+</head>
+<body>
+<h1> Using external null annotations </h1>
+<p>
+<a href="task-using_null_annotations.htm">Null annotations</a>,
+or even better, <a href="task-using_null_type_annotations.htm">null type annotations</a>
+can significantly reduce (ideally: eliminate) the danger of <code>NullPointerException</code>
+thrown at program runtime.
+Unfortunately, the API of many libraries does not yet consistently specify
+where <code>null</code> is allowed and where it isn't.
+This can be a major source of incompleteness in this endeavor.
+In order to fill this gap, starting with Eclipse 4.5 (Mars),
+JDT supports the concept of <em>external annotations</em>,
+which means that null annotations can be specified in separate files – without modifying the original library.
+If you attach such external null annotations to a given library,
+JDT will then consider these annotations for its static null analysis.<br>
+This help page describes
+</p>
+<ul>
+<li><a href="#structure">the structure of external annotations</a></li>
+<li><a href="#configure">configuring a project to use external annotations</a></li>
+<li><a href="#create">interactively creating external annotations</a></li>
+<li><a href="#inspect">inspecting external annotations</a></li>
+<li><a href="#annotation_kind">differences between declaration annotations and type annotations</a></li>
+</ul>
+<h2 id="structure">Structure of external annotations</h2>
+<p>
+External annotations can be provided as a <em>directory tree</em>,
+whose leaves are text files with extension <code>.eea</code> ("Eclipse External Annotations").
+In this structure, each directory corresponds to a Java package,
+and each <code>.eea</code> file corresponds to a Java type (class, interface etc.).
+</p>
+<p>
+Optionally, the above structure can be packed in a single zip file with extension <code>.zip</code>
+or <code>.jar</code>.
+</p>
+<p>
+The exact format of <code>.eea</code> text files has been designed with slight bias towards processing by tools.
+Still, these files are amenable to storing, comparing and merging using any version control system.
+The format is based on <em>signatures</em> as defined in
+<a target="_blank" href="http://docs.oracle.com/javase/specs/jvms/se8/html/jvms-4.html#jvms-4.7.9.1"><img src="../images/external-link-ltr-icon.svg" alt="external link"> JVMS 4.7.9.1</a>.
+<!--
+the full definition is given in TODO: write a page for doc.isv: target audience: developers of converts to/from .eea.
+ -->
+</p>
+<h2 id="configure">Configuring a project to use external annotations</h2>
+<blockquote id="caveat-configure"><strong>Caveat:</strong>
+ When different projects referring to the same library have different configurations with respect
+ to external annotations, the UI support described below (command Annotate and Javadoc hovers)
+ can easily get confused: When looking at a given library class, JDT may not know which
+ project the user is currently working on, producing unexpected results.
+ While hopefully this will be improved in a future version, for the time being users are advised
+ to use the same external annotation location for all projects referring to the same library.
+ A shared ("common") base project will typically be a good choice for hosting external annotations.
+</blockquote>
+<h3>Java Runtime Environments</h3>
+<p>
+External annotations can be directly attached to each JRE configured in the current workspace.
+For this purpose, please use the <a href="./tasks-JREs.htm">Installed JREs</a>
+preference page and click <b>Edit</b> for details of the selected JRE.
+After selecting one or more Jar files contributed by the given JRE installation,
+click <b>External Annotations</b> to open a new dialog,
+where either a directory or a zip file can be selected as the external annotation location for the selected jar(s).
+</p>
+<p>Alternatively, you may select the properties of a specific JRE bound in the
+<a href="../concepts/concept-build-classpath.htm">Java Build Path</a> of a specific project.
+Please note, that attaching external annotations to individual jars of a JRE <em>always</em> affects the workspace preference,
+even if accessed via the project's build path.
+The only way to define a project-specific location for external annotation location for a JRE is via
+the direct child <b>External annotations:</b> of the top-level node called <b>JRE System Library</b>,
+<em>but note, that project specific locations are not recommended, see the <a href="#caveat-configure">"Caveat"</a> above.</em>
+</p>
+<h3>Other Classpath Containers</h3>
+<p>Depending on the build technology in use, projects may have additional classpath containers like
+<b>Plug-in Dependencies</b> or <b>Maven Dependencies</b>.
+For these containers, the only option currently is
+to specify the external annotation location via each projects build path.
+In this case users are advised to manually ensure that the same location is used
+for all projects of the workspace, <em>see the <a href="#caveat-configure">"Caveat"</a> above.</em>
+</p>
+<h3>Other Libraries</h3>
+<p>For any other libraries (jars) explicitly referenced from the Java Build Path of a project,
+external annotations can be attached separately in the <a href="../reference/ref-properties-build-path.htm#libraries">Libraries</a> page of the project's build path.
+</p>
+<h2 id="create">Creating external annotations</h2>
+<p><u>Pre-requisites:</u>
+External annotations require a library with <a href="../reference/ref-properties-source-attachment.htm">source attachment</a>.
+Additionally, annotation based null analysis must be enabled for the current project,
+an external annotation location must be defined for the library and that location must be a directory (not a zip file) within the workspace.
+</p>
+<p>
+After navigating to the desired class, you may select the type (method parameter or method return type)
+that should be affected by an annotation,
+and invoke the new command <b>Annotate</b> (available via context menu and by default bound to <b>Ctrl-1</b>).
+Similar to quick assists in a Java source code editor,
+this command will offer proposals applicable at the current location.
+For external annotations, the three options are:
+</p>
+<ul>
+<li>Annotate as '@NonNull SomeType'</li>
+<li>Annotate as '@Nullable SomeType'</li>
+<li>Remove nullness annotation from type 'SomeType'</li>
+</ul>
+<p>
+For obvious reasons, exactly 2 of these three proposals are offered at any suitable location.
+Behind the scenes this command will create and/or update an <code>.eea</code> file corresponding to the current class.
+The new annotation will then be respected by the compiler:
+Errors and warnings in an open editor will be updated immediately;
+The <b>Problems</b> view will be updated when affected classes are re-compiled.
+</p>
+<blockquote><b>Be careful:</b>
+When attaching external annotations to a library, keep in mind that you are defining a new contract,
+that will then be used to check your program against.
+The compiler will, however, not check the library, whether it actually conforms to this contract.
+By carelessly marking, e.g., a return type as <code>@NonNull</code> you let the compiler
+advise you to remove null checks against return values from the given method.
+If the library <em>does</em> return null in any situation, this null will hit you unguarded.
+<br>
+Before adding an annotation, make sure it is backed by facts, like, e.g.:
+<ul>
+<li>explicit mention in Javadoc, e.g., when a <code>@return</code> specification says: "... or null when ...".</li>
+<li>an explicit null check of a method parameter, which does not throw an exception (implying that null is accepted → <code>@Nullable</code> parameter)</li>
+<li>uncheck dereference of a method parameter (implying that null is not accepted → <code>@NonNull</code> parameter)
+<li>an explicit <code>null</code> return (implying a <code>@Nullable</code> return type)</li>
+<li>explicitly created return values at each return statement (implying a <code>@NonNull</code> return type).</li>
+</ul>
+</blockquote>
+<h2 id="inspect">Inspecting external annotations</h2>
+<p>The immediate effect of external annotations can be observed via changes in compiler errors / warnings.
+For full transparency, annotated library signatures can be inspected using the <em>Javadoc hover</em>
+or <a href="../reference/views/ref-view-javadoc.htm">Javadoc view</a>.<br>
+<em>Due to an implementation limitation, this feature currently only works for
+<a href="./task-using_null_type_annotations.htm">type annotations</a> (Java 8).</em>
+</p>
+
+<h2 id="annotation_kind">Declaration annotations vs type annotations</h2>
+<p>Generally, support for external annotations has been developed with regard to fully supporting
+all locations of <a href="task-using_null_type_annotations.htm">null type annotations</a> (Java 8).
+This means, you may refer to any detail of a type in a method signature and annotate, e.g., a type parameter, a type bound or an array dimension.
+When using declaration annotations, the relevant subset of location shares the same mechanisms for external annotations.
+</p>
+<p>
+In one situation the design for type annotations shines through even when using declaration annotations:
+annotating an array type is based on the new syntax of type annotations (see also <a href="task-using_null_type_annotations.htm#compatibility_syntax">Compatibility > Syntax</a>).
+For illustration consider the following method in type <code>Collection</code>:
+</p>
+<pre> Object [] toArray();
+</pre>
+<p>
+Even when a project uses Java 7 or below, the return type of this method is annotated by
+placing the cursor before the array brackets.
+Invoking <b>Annotate</b> will create an external annotation that is internally interpreted
+as an annotation on the method (but still the meaning is: describing the return of this method).
+</p>
+<p>
+Other than this one exception, external annotations closely mimic how annotations directly within a source file would be handled,
+with a reduced set of locations for declaration annotations, and the full set of locations for type annotations.
+</p>
+</body>
+</html>
diff --git a/bundles/org.eclipse.jdt.doc.user/tasks/task-using_null_annotations.htm b/bundles/org.eclipse.jdt.doc.user/tasks/task-using_null_annotations.htm
index ca8c57b..59b7c84 100644
--- a/bundles/org.eclipse.jdt.doc.user/tasks/task-using_null_annotations.htm
+++ b/bundles/org.eclipse.jdt.doc.user/tasks/task-using_null_annotations.htm
@@ -1,552 +1,552 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html lang="en">
-<head>
-<meta name="copyright" content="Copyright (c) GK Software AG and others 2012, 2015. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
-<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
-<meta http-equiv="Content-Style-Type" content="text/css">
-<link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type="text/css">
-<title>Using null annotations</title>
-</head>
-<body>
-<h1> Using null annotations </h1>
-<p><code>NullPointerException</code> is one of the most common causes for failure of Java programs.
-In the simplest cases the compiler can directly warn you when it sees code like this:
-</p>
-<pre> Object o = null;
- String s = o.toString();
-</pre>
-<p>
-With branching / looping and throwing exceptions quite sophisticated <strong>flow analysis</strong>
-becomes necessary in order to figure out if a variable being dereferenced has been assigned a
-null / non-null value on some or all paths through the program.
-</p>
-<p>
-Due to the inherent complexity, flow analysis is best performed in small chunks.
-Analyzing one method at a time can be done with good tool performance -
-whereas whole-system analysis is out of scope for the Eclipse Java compiler.
-The advantage is: analysis is fast and can be done incrementally
-such that the compiler can warn you directly as you type.
-The down-side: the analysis can not "see" which values (null or non-null) are
-flowing between methods (as parameters and return values).
-</p>
-<h2 id="interprocedural_null_analysis">Inter-procedural null analysis</h2>
-<p>
-This is where null annotations come into play.
-By specifying a method parameter as <code>@NonNull</code> you can tell the compiler
-that you don't <em>want</em> a null value in this position.
-</p>
-<pre> String capitalize(@NonNull String in) {
- return in.toUpperCase(); // no null check required
- }
- void caller(String s) {
- if (s != null)
- System.out.println(capitalize(s)); // preceding null check is required
- }
-</pre>
-<p>
-In the vein of <strong>Design-by-Contract</strong> this has two sides:
-</p>
-<ol>
-<li>It's the <b>caller's</b> <b>responsibility</b> to never pass a null value,
- which is to be ensured, e.g., by an explicit null check.</li>
-<li>The <b>implementor</b> of method <code>capitalize</code> enjoys the
- <b>guarantee</b> that the argument <code>in</code> shall not be null
- and thus dereferencing without a null check is OK here.
-</ol>
-<p>
-For method return values the situation is symmetric:
-</p>
-<pre> @NonNull String getString(String maybeString) {
- if (maybeString != null)
- return maybeString; // the above null check is required
- else
- return "<n/a>";
- }
- void caller(String s) {
- System.out.println(getString(s).toUpperCase()); // no null check required
- }
-</pre>
-<ol>
-<li>Now the implementor must ensure that null is never returned.</li>
-<li>Conversely the caller now enjoys the guarantee that dereferencing the
-method result without checking is OK.
-</ol>
-<h2 id="available_annotations">Available annotations</h2>
-<p>
-The Eclipse Java compiler can be <a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#null_analysis">configured</a> to use three distinct annotation types
-for its enhanced null analysis (which is disabled by default):
-</p>
-<ul>
-<li><code>@NonNull</code>: null is not a legal value</li>
-<li><code>@Nullable</code>: null value is allowed and must be expected</li>
-<li><code>@NonNullByDefault</code>: types in method signatures and field declarations
- that lack a null annotation are regarded as non-null.</li>
-</ul>
-<p>Annotations <code>@NonNull</code> and <code>@Nullable</code> are supported in these locations:</p>
-<ul>
-<li>Method parameter</li>
-<li>Method return (syntactically a method annotation is used here)</li>
-<li>Local variables</li>
-<li>Fields</li>
-<li>In Java 8, more locations can be annotated with <a href="task-using_null_type_annotations.htm">null type annotations</a></li>
-</ul>
-<p><code>@NonNullByDefault</code> is supported for</p>
-<ul>
-<li>Methods - to affect all types in this method's signature</li>
-<li>Types (classes, interfaces, enums) - to affect all methods and fields in the type body</li>
-<li>Package (via a file <code>package-info.java</code>) - to affect all types in the package</li>
-</ul>
-<p>
-Note, that even the actual qualified names of these annotations are
-<a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#null_annotation_names">configurable</a>,
-but by default the ones given above are used (from the package <code>org.eclipse.jdt.annotation</code>).
-When using 3rd party null annotation types, please ensure that those are properly defined using at least a <code>@Target</code>
-meta annotation, because otherwise the compiler can not distinguish between declaration annotations (Java 5)
-and type annotations (Java 8). Furthermore, some <a href="#cancel_default">details of <code>@NonNullByDefault</code></a> are not supported when using
-3rd party annotation types (see <a href="task-using_null_type_annotations.htm#compatibility_semantics">here</a> for the Java 8 variant).
-</p>
-
-<h2 id="buildpath_setup">Setup of the build path</h2>
-<p>
-A JAR with the default null annotations is shipped with Eclipse in eclipse/plugins/org.eclipse.jdt.annotation_*.jar.
-This JAR needs to be on the build path at compile time but it is not necessary at run time (so you don't have to ship this to users of your compiled code).
-</p>
-<p>
-Starting with Eclipse Luna, two versions of this jar exist, one with declaration annotations for use in Java 7 or below (version 1.1.x) and one with
-<a href="task-using_null_type_annotations.htm">null type annotations</a> for use in Java 8 (version 2.0.x).
-</p>
-<p>
-<strong>For plain Java projects</strong> there is also a quick fix on unresolved references to <code>@NonNull</code>, <code>@Nullable</code>, or <code>@NonNullByDefault</code>
-that adds the suitable version of the JAR to the build path:
-</p>
-<p><img src="images/task-null-annotations-qf-simple.png" alt="Copy library with default null annotations to build path"></p>
-<p><strong>For OSGi bundles / plug-ins</strong> please add one of the following entries to your MANIFEST.MF:
-<dl>
-<dt>When using null annotations in a Java 7 project or below:</dt>
-<dd><pre>
-Require-Bundle: ...,
- org.eclipse.jdt.annotation;bundle-version="[1.1.0,2.0.0)";resolution:=optional
-</pre></dd>
-<dt>For null type annotations in a Java 8 project please use:</dt>
-<dd><pre>Require-Bundle: ...,
- org.eclipse.jdt.annotation;bundle-version="[2.0.0,3.0.0)";resolution:=optional
-</pre></dd>
-</dl>
-<p>
-See also the discussion in the corresponding section on <a href="task-using_null_type_annotations.htm#compatibility_configuration">compatibility</a>.
-</p>
-<h2 id="interpretation_of_null_annotations">Interpretation of null annotations</h2>
-<p>
-It should be clear now that null annotations add more information to your
-Java program (which can then be used by the compiler to give better warnings).
-But what exactly do we want these annotations to say?
-From a pragmatic point of view there are at least three levels of what we might
-want to express with null annotations:
-<ol>
-<li>Sporadic hints to the reader (human and compiler)</li>
-<li>Design by contract: API specification for some or all methods</li>
-<li>Full specification using an extended type system</li>
-</ol>
-<p>
-For (1) you may start using null annotations right away and without reading further,
-but you shouldn't expect more than a little hint every now and then.
-The other levels deserve some more explaining.
-</p>
-<h2 id="design_by_contract">Design by contract: API specification</h2>
-<p>
-At first sight using null annotations for API specifications in the vein of Design by Contract
-only means that the signatures of all API methods should be fully annotated,
-i.e., except for primitive types like <code>int</code> each parameter and each
-method return type should be marked as either <code>@NonNull</code> or <code>@Nullable</code>.
-Since this would mean to insert very many null annotations, it is good to know that in
-well-designed code (especially API methods), <code>@NonNull</code> is significantly more
-frequent than <code>@Nullable</code>. Thus the number of annotations can be reduced by
-declaring <code>@NonNull</code> as the <b>default</b>, using a <code>@NonNullByDefault</code>
-annotation at the package level.
-</p>
-<p>
-Note the significant difference between <code>@Nullable</code> and omitting a null annotation:
-This annotation explicitly states that null is OK and must be expected.
-By contrast, no annotation simply means, we don't know what's the intention.
-This is the old situation where sometimes both sides (caller and callee) redundantly check for null,
-and some times both sides wrongly assume that the other side will do the check.
-This is where NullPointerExceptions originate from.
-Without an annotation the compiler will not give specific advice, but with a
-<code>@Nullable</code> annotation every unchecked dereference will be flagged.
-</p>
-<p>
-With these basics we can directly map all parameter annotations to <b>pre-conditions</b> and
-interpret return annotations as <b>post-conditions</b> of the method.
-</p>
-<h3 id="override">Sub-typing and overriding</h3>
-<p>
-In object-oriented programming the concept of Design by Contract needs to address one more dimension:
-<b>sub-typing</b> and overriding (in the sequel the term "override" will be used in the sense of the
-<code>@Override</code> annotation in Java 6: methods overriding <em>or implementing</em> another method
-from a super-type). A client invoking a method like this one:
-</p>
-<pre> @NonNull String checkedString(@Nullable String in)</pre>
-<p>
-should be allowed to assume that <em>all implementations</em> of this method fulfill the contract.
-So when the method declaration is found in an interface <code>I1</code>,
-we must rule out that any class <code>Cn</code> implementing <code>I1</code> provides
-an incompatible implementation. Specifically, it is illegal if any <code>Cn</code> tries
-to override this method with an implementation that declares the parameter as <code>@NonNull</code>.
-If we <em>would</em> allow this, a client module programmed against <code>I1</code> could legally
-pass null as the argument but the implementation would assume a non-null value -
-unchecked dereference inside the method implementation would be allowed but blow up at runtime.
-Hence, a <code>@Nullable</code> parameter specification <em>obliges all overrides</em>
-to admit null as an expected, legal value.
-</p>
-<p>
-Conversely, a <code>@NonNull</code> return specification <em>obliges all overrides</em>
-to ensure that null will never be returned.
-</p>
-<p>Therefore, the compiler has to check that no override adds a <code>@NonNull</code>
-parameter annotation (or a <code>@Nullable</code> return annotation) that didn't exist in the super-type.
-</p>
-<p>
-Interestingly, the reverse redefinitions are legal: adding a <code>@Nullable</code> parameter annotation
-or a <code>@NonNull</code> return annotation (you may consider these as "improvements" of the method,
-it accepts more values and produces a more specific return value).
-</p>
-<p>By forcing sub-classes to repeat null annotations in any overriding methods, the null contract of
-each method can be understood without searching the inheritance hierarchy. However, in situations
-where an inheritance hierarchy mixes code of different provenance it may not be possible to add
-null annotations to all classes at once. In these situations the compiler can be told to treat
-methods with missing null annotations as if annotations from an overridden method were <strong>inherited</strong>.
-This is enabled using the compiler option
-<a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#inherit_null_annotations">inherit null annotations</a>.
-It is possible that a method overrides two methods with different null contracts. Also a nullness default
-can be applicable at a method which is in conflict with an inherited null annotation.
-These cases are flagged as an error and the overriding method must use an explicit null annotation to resolve the conflict.
-</p>
-<h4>Relaxing a <code>@NonNull</code> parameter to unspecified?</h4>
-<p>
-If <a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#inherit_null_annotations">inheritance of null annotations</a>
-is <em>not</em> enabled, one particular situation is safe from a type theory point of view,
-but may still indicate a problem:
-Given a super method that declares a parameter as <code>@NonNull</code> and an overriding method
-that does not constrain the corresponding parameter (neither by an explicit null annotation, nor
-by an applicable @NonNullByDefault).</p>
-<p>
-This is <b>safe</b> because clients seeing the super-declaration will be forced to avoid <code>null</code>
-whereas the the overriding implementation simply cannot leverage this guarantee due to the
-lack of a specification in this specific method.</p>
-<p>
-Still this may lead to misconceptions because it may be <b>intended</b> that the declaration
-in the super type should apply also to all overrides.</p>
-<p>
-For this reasons the compiler provides an option
-<a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#nonnull_annotation_dropped">'@NonNull' parameter not annotated in overriding method</a>:
-<ul>
-<li>Enabling this warning/error is useful for forcing developers to be explicit about the contract of overriding methods.
- If <code>null</code> should indeed be acceptable it is good practice to add a <code>@Nullable</code> annotation to
- override the <code>@NonNull</code> from the super method.</li>
-<li>Disabling this warning/error is useful in scenarii of mixed code ownership: it facilitates the use of
- legacy implementations (without null annotations) in combination with super types that have adopted
- the approach of null annotations.</li>
-</ul>
-
-<h3>Legacy super-types</h3>
-<p>
-The previous considerations add a difficulty when annotated code is written as a sub-type
-of a "legacy" (i.e., un-annotated) type (which may be from a 3rd party library, thus cannot be changed).
-If you read the last section very carefully you might have noticed that we cannot admit
-that a "legacy" method is overridden by a method with a <code>@NonNull</code> parameter
-(since clients using the super-type don't "see" the <code>@NonNull</code> obligation).
-</p>
-<p>
-In this situation you will be forced to omit null annotations
-(<em>plans exist to support adding annotations to libraries after-the-fact, but no promise can be made yet,
-if and when such a feature will be available</em>).
-</p>
-<h3 id="cancel_default">Canceling a nullness default</h3>
-<p>The situation will get tricky, if a sub-type of a "legacy" type resides in a package for which
-<code>@NonNullByDefault</code> has been specified. Now a type with an un-annotated super-type
-would need to mark all parameters in overriding methods as <code>@Nullable</code>:
-even omitting parameter annotations isn't allowed because that would be interpreted like a
-<code>@NonNull</code> parameter, which is prohibited in that position.
-That's why the Eclipse Java compiler supports cancellation
-of a nullness default: by annotating a method or type with <code>@NonNullByDefault(false)</code>
-an applicable default will be canceled for this element, and un-annotated parameters are again interpreted as
-unspecified. Now, sub-typing is legal again without adding unwanted <code>@Nullable</code>
-annotations:
-</p>
-<pre>class LegacyClass {
- String enhance (String in) { // clients are not forced to pass nonnull.
- return in.toUpperCase();
- }
-}
-
-@NonNullByDefault
-class MyClass extends LegacyClass {
-
- // ... methods with @NonNull default ...
-
- @Override
- @NonNullByDefault(false)
- String enhance(String in) { // would not be valid if @NonNullByDefault were effective here
- return super.enhance(in);
- }
-}
-</pre>
-<p>Canceling a nullness default may not be possible when using annotation types other than
-<code>org.eclipse.jdt.annotation.NonNullByDefault</code> supplied by Eclipse,
-because other annotation types may not declare the boolean property that is used here.</p>
-<h3 id="fields">The case of fields</h3>
-<p>Null annotations work best when applied in <b>method signatures</b> (<b>local variables</b>
-typically don't even need these, but may also leverage null annotations for bridging between
-annotated code and "legacy" code).
-In such usage null annotations connect the chunks of intra procedural analysis as to achieve
-statements about global data flows. Starting with Eclipse Kepler null annotations can also be
-applied to <b>fields</b>, but here the situation is slightly different.</p>
-<p>Consider a field marked with <b><code>@NonNull</code></b>: this obviously requires that any
-assignment to the field provides a value that is known not to be null.
-Additionally, the compiler must be able to verify that a non-null field can never be accessed
-in its <b>uninitialized state</b> (in which it still has the value <code>null</code>).
-If it can be verified that every <b>constructor</b> complies to this rule (similarly a static
-field must have an initializer), the program benefits from the safety that dereferencing
-the field can never cause a <code>NullPointerException</code>.</p>
-<p>The situation is more delicate when considering a field marked <b><code>@Nullable</code></b>.
-Such a field should always be considered as dangerous and the recommended way of working
-with nullable fields is: <b>always assign the value to a local variable before working with it</b>.
-Using a local variable the flow analysis can tell exactly, whether a dereference is
-sufficiently protected by a null check. When following this general rule working with nullable
-fields poses no problems.</p>
-<p>Things get more involved when the code directly dereferences the value of a nullable field.
-The problem is that any null checks that the code may perform before the dereference can
-easily be invalidated by one of these:</p>
-<ul>
-<li>effects via aliased references</li>
-<li>side effects of another method</li>
-<li>concurrency</li>
-</ul>
-<p>One can easily see that without also analyzing thread synchronization (which is beyond
-the compiler's capabilities) no null-check against a nullable field will ever grant
-100% safety for a subsequent dereference. So if concurrent access to a nullable field
-is possible, the field's value should <em>never</em> be directly dereferenced,
-<em>always</em> a local variable should be used instead.
-Even if no concurrency is involved, the remaining issues pose a challenge to a
-complete analysis that is harder than what a compiler can typically handle.</p>
-<h4 id="syntactic_analysis">Flow analysis vs. syntactic analysis</h4>
-<p>Given the compiler cannot fully analyze the effects of aliasing, side effects and
-concurrency, <b>the Eclipse compiler does not perform any flow analysis for fields</b>
-(other than regarding their initialization). Since many developers will consider this
-limitation as too restrictive - requiring the use of local variables where developers
-<em>feel</em> that their code should actually be safe - a new option has been introduced
-as a tentative compromise:</p>
-<p>The compiler can be configured to perform some
-<a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#syntactic_null_analysis_for_fields"><b>syntactic analysis</b></a>.
-This will detect the most obvious patterns like this:
-<pre>
- @Nullable Object f;
- void printChecked() {
- if (this.f != null)
- System.out.println(this.f.toString());
- }
-</pre>
-<p>
-With the given option enabled the above code will not be flagged by the compiler.
-It is important to see that this syntactic analysis is not "smart" in any way.
-If any code appears between the check and the dereference the compiler will cowardly
-"forget" the information of the previous null check, without even trying to see if
-the intermediate code could perhaps be harmless according to some criteria.
-Thus <b>please be advised</b>: whenever the compiler flags a dereference of a nullable field
-as unsafe although the human eye may see that null should not occur, please either
-rewrite your code to closely follow the recognized pattern shown above, or, even better:
-use a local variable to leverage all the sophistication of flow analysis, which syntactic
-analysis will never attain.
-</p>
-<h3>Benefits of Design-by-Contract</h3>
-<p>
-Using null annotations in the style of Design-by-Contract as outlined above,
-helps to improve the <b>quality</b> of your Java code in several ways:
-At the interface between methods it is made explicit, which parameters / returns
-tolerate a null value and which ones don't. This captures design decisions,
-which are highly relevant to the developers, in a way that is also checkable by the compiler.
-</p>
-<p>
-Additionally, based on this interface specification the intra-procedural flow analysis can
-pick up available information and give much more precise errors/warnings.
-Without annotations any value flowing into or out of a method has unknown nullness
-and therefore null analysis remains silent about their usage.
-With API-level null annotations the nullness of most values is actually known,
-and significantly fewer NPEs will go unnoticed by the compiler.
-However, you should be aware that still some loopholes exist, where unspecified
-values flow into the analysis, preventing a complete statement whether NPEs can
-occur at runtime.
-</p>
-<h2 id="complete_specification">Complete specification using an extended type system</h2>
-<p>
-The support for null annotations had been designed in a way that should be compatible to
-a future extension.
-This extension has become part of the Java language as <strong>type annotations (JSR 308)</strong>,
-which have been introduced in Java 8.
-JDT supports to leverage the new concept for
-<a href="task-using_null_type_annotations.htm">null type annotations</a>.
-</p>
-<h2 id="compiler_messages_explained">Compiler messages explained</h2>
-<p>
-Semantic details of annotation based null analysis are presented here, by explaining the rules
-that the compiler checks and the messages it issues upon violation of a rule.
-</p>
-<p>
-On the corresponding <a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm">preference page</a>
-the individual rules checked by the compiler are grouped under the following headings:
-</p>
-<h3>Violation of null specification</h3>
-<p>As specification violation we handle any situation where a null annotation
-makes a claim that is violated by the actual implementation. The typical situation results
-from specifying a value (local, argument, method return) as <code>@NonNull</code> whereas
-the implementation actually provides a nullable value. Here an expression is considered as
-nullable if either it is statically known to evaluate to the value null, or if it is declared
-with a <code>@Nullable</code> annotation.
-</p>
-<p>Secondly, this group also contains the rules for method overriding as discussed
-<a href="#override">above</a>.
-Here a super method establishes a claim (e.g., that null is a legal argument)
-while an override tries to evade this claim (by assuming that null is <i>not</i> a legal argument).
-As mentioned even specializing an argument from un-annotated to <code>@NonNull</code>
-is a specification violation, because it introduces a contract that should bind the client
-(to not pass null), but a client using the super-type won't even see this contract,
-so he doesn't even know what is expected of him.
-</p>
-<p>
-The full list of situations regarded as specification violations is given
-<a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#null_spec_violation">here</a>.
-It is important to understand that errors in this group <b>should never be ignored</b>,
-because otherwise the entire null analysis will be performed based on false assumptions.
-Specifically, whenever the compiler sees a value with a <code>@NonNull</code> annotation
-it takes it for granted that null will not occur at runtime.
-It's the rules about specification violations which ensure that this reasoning is sound.
-Therefore it is strongly recommended to leave this kind of problem configured as <b>errors</b>.
-</p>
-<h3>Conflict between null annotations and null inference</h3>
-<p>
-Also this group of rules watches over the adherence to null specifications.
-However, here we deal with values that are not <em>declared</em> as <code>@Nullable</code>
-(nor the value null itself), but values where the <b>intra-procedural flow analysis</b>
-<i>infers</i> that null can possibly occur on some execution path.
-</p>
-<p>
-This situation arises from the fact that for un-annotated local variables
-the compiler will infer whether null is possible using its flow analysis.
-Assuming that this analysis is accurate, if it sees a problem this problem has the
-same severity as direct violations of a null specification.
-Therefore, it is again strongly recommended to leave these problems configured as <b>errors</b>
-and not to ignore these messages.
-</p>
-<p>
-Creating a separate group for these problems serves two purposes: to document that
-a given problem was raised with the help of the flow analysis, and: to account for
-the fact that this flow analysis <em>could</em> be at fault (because of a bug in the
-implementation).
-For the case of an acknowledged implementation bug it could in exceptional situations
-be OK to suppress an error message of this kind.
-</p>
-<p>
-Given the nature of any static analysis, the flow analysis may fail to see that a
-certain combination of execution paths and values is not possible. As an example
-consider <em>variable correlation</em>:
-</p>
-<pre> String flatten(String[] inputs1, String[] inputs2) {
- StringBuffer sb1 = null, sb2 = null;
- int len = Math.min(inputs1.length, inputs2.length);
- for (int i=0; i<len; i++) {
- if (sb1 == null) {
- sb1 = new StringBuffer();
- sb2 = new StringBuffer();
- }
- sb1.append(inputs1[i]);
- sb2.append(inputs2[i]); // warning here
- }
- if (sb1 != null) return sb1.append(sb2).toString();
- return "";
- }
-</pre>
-<p>
-The compiler will report a potential null pointer access at the invocation of <code>sb2.append(..)</code>.
-The human reader can see that there is no actual danger because <code>sb1</code> and <code>sb2</code>
-actually correlate in a way that either both variables are null or both are not null.
-At the line in question we know that <code>sb1</code> is not null, hence also <code>sb2</code>
-is not null. Without going into the details why such correlation analysis is beyond the capability
-of the Eclipse Java compiler, please just keep in mind that this analysis doesn't have the power of a
-full theorem prover and therefore pessimistically reports some problems which a more capable
-analysis could possibly identify as false alarms.
-</p>
-<p>
-If you want to benefit from flow analysis, you are advised to give a little help to the compiler
-so it can "see" your conclusions. This help can be as simple as splitting the <code>if (sb1 == null)</code>
-into two separate ifs, one for each local variable, which is a very small price to pay for the
-gain that now the compiler can exactly see what happens and check your code accordingly.
-More discussion on this topic will follow <a href="#tips_analyzable">below</a>.
-</p>
-<h3>Unchecked conversion from non-annotated type to @NonNull type</h3>
-<p>
-This group of problems is based on the following analogy: in a program using Java 5 generics
-any calls to pre-Java-5 libraries may expose raw types, i.e., applications of a generic type
-which fail to specify concrete type arguments. To fit such values into a program using
-generics the compiler can add an <i>implicit conversion</i> by assuming that type arguments were
-specified in the way expected by the client part of the code.
-The compiler will issue a warning about the use of such a conversion and proceed its type checking
-assuming the library "does the right thing".
-In exactly the same way, an un-annotated return type of a library method can be considered
-as a "raw" or "legacy" type.
-Again an <i>implicit conversion</i> can optimistically assume the expected specification.
-Again a warning is issued and analysis continues assuming that the library "does the right thing".
-</p>
-<p>
-Theoretically speaking, also the need for such implicit conversions indicates a specification
-violation. However, in this case it may be 3rd party code that violates the specification which our
-code expects. Or, maybe (as we have convinced ourselves of) some 3rd party code does fulfill the
-contract, but only fails to declare so (because it doesn't use null annotations).
-In such situations we may not be able to exactly fix the problem for <em>organizational</em> reasons.
-</p>
-<pre> @SuppressWarnings("null")
- @NonNull Foo foo = Library.getFoo(); // implicit conversion
- foo.bar();
-</pre>
-<p>
-The above code snippet assumes that <code>Library.getFoo()</code> returns a <code>Foo</code>
-without specifying a null annotation. We can integrate the return value into our annotated
-program by assignment to a <code>@NonNull</code> local variable, which triggers a warning
-regarding an unchecked conversion.
-By adding a corresponding <code>SuppressWarnings("null")</code> to this declaration
-we acknowledge the inherent danger and accept the responsibility of having verified that
-the library actually behaves as desired.
-</p>
-<h2 id="tips_analyzable">Tips for making code better analyzable</h2>
-<p>
-If flow analysis cannot see that a value is indeed not null, the simplest strategy is always
-to add a new scoped local variable annotated with <code>@NonNull</code>.
-Then, if you are convinced that the value assigned to this local will never be null at runtime you can use a helper methods like this:
-</p>
-<pre> static @NonNull <T> T assertNonNull(@Nullable T value, @Nullable String msg) {
- if (value == null) throw new AssertionError(msg);
- return value;
- }
- @NonNull MyType foo() {
- if (isInitialized()) {
- MyType couldBeNull = getObjectOrNull();
- @NonNull MyType theValue = assertNonNull(couldBeNull,
- "value should not be null because application " +
- "is fully initialized at this point.");
- return theValue;
- }
- return new MyTypeImpl();
- }</pre>
-<p>
-Note that by using the above <code>assertNonNull()</code> method you are accepting the responsibility
-that this assertion will always hold at runtime.
-If that is not what you want, annotated local variables will still help to narrow down where and why the analysis
-sees a potential for null flowing into a certain location.
-</p>
-<h2 id="tips_adoption">Tips for adopting null annotations</h2>
-<p>
-At the time of releasing the JDT version 3.8.0, collecting advice for adopting null annotations is
-still work in progress. For that reason this information is currently maintained in the
-<a href="http://wiki.eclipse.org/JDT_Core/Null_Analysis/Adopting_Null_Annotations">Eclipse wiki</a>.
-</p>
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+<head>
+<meta name="copyright" content="Copyright (c) GK Software AG and others 2012, 2015. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
+<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type="text/css">
+<title>Using null annotations</title>
+</head>
+<body>
+<h1> Using null annotations </h1>
+<p><code>NullPointerException</code> is one of the most common causes for failure of Java programs.
+In the simplest cases the compiler can directly warn you when it sees code like this:
+</p>
+<pre> Object o = null;
+ String s = o.toString();
+</pre>
+<p>
+With branching / looping and throwing exceptions quite sophisticated <strong>flow analysis</strong>
+becomes necessary in order to figure out if a variable being dereferenced has been assigned a
+null / non-null value on some or all paths through the program.
+</p>
+<p>
+Due to the inherent complexity, flow analysis is best performed in small chunks.
+Analyzing one method at a time can be done with good tool performance -
+whereas whole-system analysis is out of scope for the Eclipse Java compiler.
+The advantage is: analysis is fast and can be done incrementally
+such that the compiler can warn you directly as you type.
+The down-side: the analysis can not "see" which values (null or non-null) are
+flowing between methods (as parameters and return values).
+</p>
+<h2 id="interprocedural_null_analysis">Inter-procedural null analysis</h2>
+<p>
+This is where null annotations come into play.
+By specifying a method parameter as <code>@NonNull</code> you can tell the compiler
+that you don't <em>want</em> a null value in this position.
+</p>
+<pre> String capitalize(@NonNull String in) {
+ return in.toUpperCase(); // no null check required
+ }
+ void caller(String s) {
+ if (s != null)
+ System.out.println(capitalize(s)); // preceding null check is required
+ }
+</pre>
+<p>
+In the vein of <strong>Design-by-Contract</strong> this has two sides:
+</p>
+<ol>
+<li>It's the <b>caller's</b> <b>responsibility</b> to never pass a null value,
+ which is to be ensured, e.g., by an explicit null check.</li>
+<li>The <b>implementor</b> of method <code>capitalize</code> enjoys the
+ <b>guarantee</b> that the argument <code>in</code> shall not be null
+ and thus dereferencing without a null check is OK here.
+</ol>
+<p>
+For method return values the situation is symmetric:
+</p>
+<pre> @NonNull String getString(String maybeString) {
+ if (maybeString != null)
+ return maybeString; // the above null check is required
+ else
+ return "<n/a>";
+ }
+ void caller(String s) {
+ System.out.println(getString(s).toUpperCase()); // no null check required
+ }
+</pre>
+<ol>
+<li>Now the implementor must ensure that null is never returned.</li>
+<li>Conversely the caller now enjoys the guarantee that dereferencing the
+method result without checking is OK.
+</ol>
+<h2 id="available_annotations">Available annotations</h2>
+<p>
+The Eclipse Java compiler can be <a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#null_analysis">configured</a> to use three distinct annotation types
+for its enhanced null analysis (which is disabled by default):
+</p>
+<ul>
+<li><code>@NonNull</code>: null is not a legal value</li>
+<li><code>@Nullable</code>: null value is allowed and must be expected</li>
+<li><code>@NonNullByDefault</code>: types in method signatures and field declarations
+ that lack a null annotation are regarded as non-null.</li>
+</ul>
+<p>Annotations <code>@NonNull</code> and <code>@Nullable</code> are supported in these locations:</p>
+<ul>
+<li>Method parameter</li>
+<li>Method return (syntactically a method annotation is used here)</li>
+<li>Local variables</li>
+<li>Fields</li>
+<li>In Java 8, more locations can be annotated with <a href="task-using_null_type_annotations.htm">null type annotations</a></li>
+</ul>
+<p><code>@NonNullByDefault</code> is supported for</p>
+<ul>
+<li>Methods - to affect all types in this method's signature</li>
+<li>Types (classes, interfaces, enums) - to affect all methods and fields in the type body</li>
+<li>Package (via a file <code>package-info.java</code>) - to affect all types in the package</li>
+</ul>
+<p>
+Note, that even the actual qualified names of these annotations are
+<a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#null_annotation_names">configurable</a>,
+but by default the ones given above are used (from the package <code>org.eclipse.jdt.annotation</code>).
+When using 3rd party null annotation types, please ensure that those are properly defined using at least a <code>@Target</code>
+meta annotation, because otherwise the compiler can not distinguish between declaration annotations (Java 5)
+and type annotations (Java 8). Furthermore, some <a href="#cancel_default">details of <code>@NonNullByDefault</code></a> are not supported when using
+3rd party annotation types (see <a href="task-using_null_type_annotations.htm#compatibility_semantics">here</a> for the Java 8 variant).
+</p>
+
+<h2 id="buildpath_setup">Setup of the build path</h2>
+<p>
+A JAR with the default null annotations is shipped with Eclipse in eclipse/plugins/org.eclipse.jdt.annotation_*.jar.
+This JAR needs to be on the build path at compile time but it is not necessary at run time (so you don't have to ship this to users of your compiled code).
+</p>
+<p>
+Starting with Eclipse Luna, two versions of this jar exist, one with declaration annotations for use in Java 7 or below (version 1.1.x) and one with
+<a href="task-using_null_type_annotations.htm">null type annotations</a> for use in Java 8 (version 2.0.x).
+</p>
+<p>
+<strong>For plain Java projects</strong> there is also a quick fix on unresolved references to <code>@NonNull</code>, <code>@Nullable</code>, or <code>@NonNullByDefault</code>
+that adds the suitable version of the JAR to the build path:
+</p>
+<p><img src="images/task-null-annotations-qf-simple.png" alt="Copy library with default null annotations to build path"></p>
+<p><strong>For OSGi bundles / plug-ins</strong> please add one of the following entries to your MANIFEST.MF:
+<dl>
+<dt>When using null annotations in a Java 7 project or below:</dt>
+<dd><pre>
+Require-Bundle: ...,
+ org.eclipse.jdt.annotation;bundle-version="[1.1.0,2.0.0)";resolution:=optional
+</pre></dd>
+<dt>For null type annotations in a Java 8 project please use:</dt>
+<dd><pre>Require-Bundle: ...,
+ org.eclipse.jdt.annotation;bundle-version="[2.0.0,3.0.0)";resolution:=optional
+</pre></dd>
+</dl>
+<p>
+See also the discussion in the corresponding section on <a href="task-using_null_type_annotations.htm#compatibility_configuration">compatibility</a>.
+</p>
+<h2 id="interpretation_of_null_annotations">Interpretation of null annotations</h2>
+<p>
+It should be clear now that null annotations add more information to your
+Java program (which can then be used by the compiler to give better warnings).
+But what exactly do we want these annotations to say?
+From a pragmatic point of view there are at least three levels of what we might
+want to express with null annotations:
+<ol>
+<li>Sporadic hints to the reader (human and compiler)</li>
+<li>Design by contract: API specification for some or all methods</li>
+<li>Full specification using an extended type system</li>
+</ol>
+<p>
+For (1) you may start using null annotations right away and without reading further,
+but you shouldn't expect more than a little hint every now and then.
+The other levels deserve some more explaining.
+</p>
+<h2 id="design_by_contract">Design by contract: API specification</h2>
+<p>
+At first sight using null annotations for API specifications in the vein of Design by Contract
+only means that the signatures of all API methods should be fully annotated,
+i.e., except for primitive types like <code>int</code> each parameter and each
+method return type should be marked as either <code>@NonNull</code> or <code>@Nullable</code>.
+Since this would mean to insert very many null annotations, it is good to know that in
+well-designed code (especially API methods), <code>@NonNull</code> is significantly more
+frequent than <code>@Nullable</code>. Thus the number of annotations can be reduced by
+declaring <code>@NonNull</code> as the <b>default</b>, using a <code>@NonNullByDefault</code>
+annotation at the package level.
+</p>
+<p>
+Note the significant difference between <code>@Nullable</code> and omitting a null annotation:
+This annotation explicitly states that null is OK and must be expected.
+By contrast, no annotation simply means, we don't know what's the intention.
+This is the old situation where sometimes both sides (caller and callee) redundantly check for null,
+and some times both sides wrongly assume that the other side will do the check.
+This is where NullPointerExceptions originate from.
+Without an annotation the compiler will not give specific advice, but with a
+<code>@Nullable</code> annotation every unchecked dereference will be flagged.
+</p>
+<p>
+With these basics we can directly map all parameter annotations to <b>pre-conditions</b> and
+interpret return annotations as <b>post-conditions</b> of the method.
+</p>
+<h3 id="override">Sub-typing and overriding</h3>
+<p>
+In object-oriented programming the concept of Design by Contract needs to address one more dimension:
+<b>sub-typing</b> and overriding (in the sequel the term "override" will be used in the sense of the
+<code>@Override</code> annotation in Java 6: methods overriding <em>or implementing</em> another method
+from a super-type). A client invoking a method like this one:
+</p>
+<pre> @NonNull String checkedString(@Nullable String in)</pre>
+<p>
+should be allowed to assume that <em>all implementations</em> of this method fulfill the contract.
+So when the method declaration is found in an interface <code>I1</code>,
+we must rule out that any class <code>Cn</code> implementing <code>I1</code> provides
+an incompatible implementation. Specifically, it is illegal if any <code>Cn</code> tries
+to override this method with an implementation that declares the parameter as <code>@NonNull</code>.
+If we <em>would</em> allow this, a client module programmed against <code>I1</code> could legally
+pass null as the argument but the implementation would assume a non-null value -
+unchecked dereference inside the method implementation would be allowed but blow up at runtime.
+Hence, a <code>@Nullable</code> parameter specification <em>obliges all overrides</em>
+to admit null as an expected, legal value.
+</p>
+<p>
+Conversely, a <code>@NonNull</code> return specification <em>obliges all overrides</em>
+to ensure that null will never be returned.
+</p>
+<p>Therefore, the compiler has to check that no override adds a <code>@NonNull</code>
+parameter annotation (or a <code>@Nullable</code> return annotation) that didn't exist in the super-type.
+</p>
+<p>
+Interestingly, the reverse redefinitions are legal: adding a <code>@Nullable</code> parameter annotation
+or a <code>@NonNull</code> return annotation (you may consider these as "improvements" of the method,
+it accepts more values and produces a more specific return value).
+</p>
+<p>By forcing sub-classes to repeat null annotations in any overriding methods, the null contract of
+each method can be understood without searching the inheritance hierarchy. However, in situations
+where an inheritance hierarchy mixes code of different provenance it may not be possible to add
+null annotations to all classes at once. In these situations the compiler can be told to treat
+methods with missing null annotations as if annotations from an overridden method were <strong>inherited</strong>.
+This is enabled using the compiler option
+<a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#inherit_null_annotations">inherit null annotations</a>.
+It is possible that a method overrides two methods with different null contracts. Also a nullness default
+can be applicable at a method which is in conflict with an inherited null annotation.
+These cases are flagged as an error and the overriding method must use an explicit null annotation to resolve the conflict.
+</p>
+<h4>Relaxing a <code>@NonNull</code> parameter to unspecified?</h4>
+<p>
+If <a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#inherit_null_annotations">inheritance of null annotations</a>
+is <em>not</em> enabled, one particular situation is safe from a type theory point of view,
+but may still indicate a problem:
+Given a super method that declares a parameter as <code>@NonNull</code> and an overriding method
+that does not constrain the corresponding parameter (neither by an explicit null annotation, nor
+by an applicable @NonNullByDefault).</p>
+<p>
+This is <b>safe</b> because clients seeing the super-declaration will be forced to avoid <code>null</code>
+whereas the the overriding implementation simply cannot leverage this guarantee due to the
+lack of a specification in this specific method.</p>
+<p>
+Still this may lead to misconceptions because it may be <b>intended</b> that the declaration
+in the super type should apply also to all overrides.</p>
+<p>
+For this reasons the compiler provides an option
+<a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#nonnull_annotation_dropped">'@NonNull' parameter not annotated in overriding method</a>:
+<ul>
+<li>Enabling this warning/error is useful for forcing developers to be explicit about the contract of overriding methods.
+ If <code>null</code> should indeed be acceptable it is good practice to add a <code>@Nullable</code> annotation to
+ override the <code>@NonNull</code> from the super method.</li>
+<li>Disabling this warning/error is useful in scenarii of mixed code ownership: it facilitates the use of
+ legacy implementations (without null annotations) in combination with super types that have adopted
+ the approach of null annotations.</li>
+</ul>
+
+<h3>Legacy super-types</h3>
+<p>
+The previous considerations add a difficulty when annotated code is written as a sub-type
+of a "legacy" (i.e., un-annotated) type (which may be from a 3rd party library, thus cannot be changed).
+If you read the last section very carefully you might have noticed that we cannot admit
+that a "legacy" method is overridden by a method with a <code>@NonNull</code> parameter
+(since clients using the super-type don't "see" the <code>@NonNull</code> obligation).
+</p>
+<p>
+In this situation you will be forced to omit null annotations
+(<em>plans exist to support adding annotations to libraries after-the-fact, but no promise can be made yet,
+if and when such a feature will be available</em>).
+</p>
+<h3 id="cancel_default">Canceling a nullness default</h3>
+<p>The situation will get tricky, if a sub-type of a "legacy" type resides in a package for which
+<code>@NonNullByDefault</code> has been specified. Now a type with an un-annotated super-type
+would need to mark all parameters in overriding methods as <code>@Nullable</code>:
+even omitting parameter annotations isn't allowed because that would be interpreted like a
+<code>@NonNull</code> parameter, which is prohibited in that position.
+That's why the Eclipse Java compiler supports cancellation
+of a nullness default: by annotating a method or type with <code>@NonNullByDefault(false)</code>
+an applicable default will be canceled for this element, and un-annotated parameters are again interpreted as
+unspecified. Now, sub-typing is legal again without adding unwanted <code>@Nullable</code>
+annotations:
+</p>
+<pre>class LegacyClass {
+ String enhance (String in) { // clients are not forced to pass nonnull.
+ return in.toUpperCase();
+ }
+}
+
+@NonNullByDefault
+class MyClass extends LegacyClass {
+
+ // ... methods with @NonNull default ...
+
+ @Override
+ @NonNullByDefault(false)
+ String enhance(String in) { // would not be valid if @NonNullByDefault were effective here
+ return super.enhance(in);
+ }
+}
+</pre>
+<p>Canceling a nullness default may not be possible when using annotation types other than
+<code>org.eclipse.jdt.annotation.NonNullByDefault</code> supplied by Eclipse,
+because other annotation types may not declare the boolean property that is used here.</p>
+<h3 id="fields">The case of fields</h3>
+<p>Null annotations work best when applied in <b>method signatures</b> (<b>local variables</b>
+typically don't even need these, but may also leverage null annotations for bridging between
+annotated code and "legacy" code).
+In such usage null annotations connect the chunks of intra procedural analysis as to achieve
+statements about global data flows. Starting with Eclipse Kepler null annotations can also be
+applied to <b>fields</b>, but here the situation is slightly different.</p>
+<p>Consider a field marked with <b><code>@NonNull</code></b>: this obviously requires that any
+assignment to the field provides a value that is known not to be null.
+Additionally, the compiler must be able to verify that a non-null field can never be accessed
+in its <b>uninitialized state</b> (in which it still has the value <code>null</code>).
+If it can be verified that every <b>constructor</b> complies to this rule (similarly a static
+field must have an initializer), the program benefits from the safety that dereferencing
+the field can never cause a <code>NullPointerException</code>.</p>
+<p>The situation is more delicate when considering a field marked <b><code>@Nullable</code></b>.
+Such a field should always be considered as dangerous and the recommended way of working
+with nullable fields is: <b>always assign the value to a local variable before working with it</b>.
+Using a local variable the flow analysis can tell exactly, whether a dereference is
+sufficiently protected by a null check. When following this general rule working with nullable
+fields poses no problems.</p>
+<p>Things get more involved when the code directly dereferences the value of a nullable field.
+The problem is that any null checks that the code may perform before the dereference can
+easily be invalidated by one of these:</p>
+<ul>
+<li>effects via aliased references</li>
+<li>side effects of another method</li>
+<li>concurrency</li>
+</ul>
+<p>One can easily see that without also analyzing thread synchronization (which is beyond
+the compiler's capabilities) no null-check against a nullable field will ever grant
+100% safety for a subsequent dereference. So if concurrent access to a nullable field
+is possible, the field's value should <em>never</em> be directly dereferenced,
+<em>always</em> a local variable should be used instead.
+Even if no concurrency is involved, the remaining issues pose a challenge to a
+complete analysis that is harder than what a compiler can typically handle.</p>
+<h4 id="syntactic_analysis">Flow analysis vs. syntactic analysis</h4>
+<p>Given the compiler cannot fully analyze the effects of aliasing, side effects and
+concurrency, <b>the Eclipse compiler does not perform any flow analysis for fields</b>
+(other than regarding their initialization). Since many developers will consider this
+limitation as too restrictive - requiring the use of local variables where developers
+<em>feel</em> that their code should actually be safe - a new option has been introduced
+as a tentative compromise:</p>
+<p>The compiler can be configured to perform some
+<a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#syntactic_null_analysis_for_fields"><b>syntactic analysis</b></a>.
+This will detect the most obvious patterns like this:
+<pre>
+ @Nullable Object f;
+ void printChecked() {
+ if (this.f != null)
+ System.out.println(this.f.toString());
+ }
+</pre>
+<p>
+With the given option enabled the above code will not be flagged by the compiler.
+It is important to see that this syntactic analysis is not "smart" in any way.
+If any code appears between the check and the dereference the compiler will cowardly
+"forget" the information of the previous null check, without even trying to see if
+the intermediate code could perhaps be harmless according to some criteria.
+Thus <b>please be advised</b>: whenever the compiler flags a dereference of a nullable field
+as unsafe although the human eye may see that null should not occur, please either
+rewrite your code to closely follow the recognized pattern shown above, or, even better:
+use a local variable to leverage all the sophistication of flow analysis, which syntactic
+analysis will never attain.
+</p>
+<h3>Benefits of Design-by-Contract</h3>
+<p>
+Using null annotations in the style of Design-by-Contract as outlined above,
+helps to improve the <b>quality</b> of your Java code in several ways:
+At the interface between methods it is made explicit, which parameters / returns
+tolerate a null value and which ones don't. This captures design decisions,
+which are highly relevant to the developers, in a way that is also checkable by the compiler.
+</p>
+<p>
+Additionally, based on this interface specification the intra-procedural flow analysis can
+pick up available information and give much more precise errors/warnings.
+Without annotations any value flowing into or out of a method has unknown nullness
+and therefore null analysis remains silent about their usage.
+With API-level null annotations the nullness of most values is actually known,
+and significantly fewer NPEs will go unnoticed by the compiler.
+However, you should be aware that still some loopholes exist, where unspecified
+values flow into the analysis, preventing a complete statement whether NPEs can
+occur at runtime.
+</p>
+<h2 id="complete_specification">Complete specification using an extended type system</h2>
+<p>
+The support for null annotations had been designed in a way that should be compatible to
+a future extension.
+This extension has become part of the Java language as <strong>type annotations (JSR 308)</strong>,
+which have been introduced in Java 8.
+JDT supports to leverage the new concept for
+<a href="task-using_null_type_annotations.htm">null type annotations</a>.
+</p>
+<h2 id="compiler_messages_explained">Compiler messages explained</h2>
+<p>
+Semantic details of annotation based null analysis are presented here, by explaining the rules
+that the compiler checks and the messages it issues upon violation of a rule.
+</p>
+<p>
+On the corresponding <a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm">preference page</a>
+the individual rules checked by the compiler are grouped under the following headings:
+</p>
+<h3>Violation of null specification</h3>
+<p>As specification violation we handle any situation where a null annotation
+makes a claim that is violated by the actual implementation. The typical situation results
+from specifying a value (local, argument, method return) as <code>@NonNull</code> whereas
+the implementation actually provides a nullable value. Here an expression is considered as
+nullable if either it is statically known to evaluate to the value null, or if it is declared
+with a <code>@Nullable</code> annotation.
+</p>
+<p>Secondly, this group also contains the rules for method overriding as discussed
+<a href="#override">above</a>.
+Here a super method establishes a claim (e.g., that null is a legal argument)
+while an override tries to evade this claim (by assuming that null is <i>not</i> a legal argument).
+As mentioned even specializing an argument from un-annotated to <code>@NonNull</code>
+is a specification violation, because it introduces a contract that should bind the client
+(to not pass null), but a client using the super-type won't even see this contract,
+so he doesn't even know what is expected of him.
+</p>
+<p>
+The full list of situations regarded as specification violations is given
+<a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#null_spec_violation">here</a>.
+It is important to understand that errors in this group <b>should never be ignored</b>,
+because otherwise the entire null analysis will be performed based on false assumptions.
+Specifically, whenever the compiler sees a value with a <code>@NonNull</code> annotation
+it takes it for granted that null will not occur at runtime.
+It's the rules about specification violations which ensure that this reasoning is sound.
+Therefore it is strongly recommended to leave this kind of problem configured as <b>errors</b>.
+</p>
+<h3>Conflict between null annotations and null inference</h3>
+<p>
+Also this group of rules watches over the adherence to null specifications.
+However, here we deal with values that are not <em>declared</em> as <code>@Nullable</code>
+(nor the value null itself), but values where the <b>intra-procedural flow analysis</b>
+<i>infers</i> that null can possibly occur on some execution path.
+</p>
+<p>
+This situation arises from the fact that for un-annotated local variables
+the compiler will infer whether null is possible using its flow analysis.
+Assuming that this analysis is accurate, if it sees a problem this problem has the
+same severity as direct violations of a null specification.
+Therefore, it is again strongly recommended to leave these problems configured as <b>errors</b>
+and not to ignore these messages.
+</p>
+<p>
+Creating a separate group for these problems serves two purposes: to document that
+a given problem was raised with the help of the flow analysis, and: to account for
+the fact that this flow analysis <em>could</em> be at fault (because of a bug in the
+implementation).
+For the case of an acknowledged implementation bug it could in exceptional situations
+be OK to suppress an error message of this kind.
+</p>
+<p>
+Given the nature of any static analysis, the flow analysis may fail to see that a
+certain combination of execution paths and values is not possible. As an example
+consider <em>variable correlation</em>:
+</p>
+<pre> String flatten(String[] inputs1, String[] inputs2) {
+ StringBuffer sb1 = null, sb2 = null;
+ int len = Math.min(inputs1.length, inputs2.length);
+ for (int i=0; i<len; i++) {
+ if (sb1 == null) {
+ sb1 = new StringBuffer();
+ sb2 = new StringBuffer();
+ }
+ sb1.append(inputs1[i]);
+ sb2.append(inputs2[i]); // warning here
+ }
+ if (sb1 != null) return sb1.append(sb2).toString();
+ return "";
+ }
+</pre>
+<p>
+The compiler will report a potential null pointer access at the invocation of <code>sb2.append(..)</code>.
+The human reader can see that there is no actual danger because <code>sb1</code> and <code>sb2</code>
+actually correlate in a way that either both variables are null or both are not null.
+At the line in question we know that <code>sb1</code> is not null, hence also <code>sb2</code>
+is not null. Without going into the details why such correlation analysis is beyond the capability
+of the Eclipse Java compiler, please just keep in mind that this analysis doesn't have the power of a
+full theorem prover and therefore pessimistically reports some problems which a more capable
+analysis could possibly identify as false alarms.
+</p>
+<p>
+If you want to benefit from flow analysis, you are advised to give a little help to the compiler
+so it can "see" your conclusions. This help can be as simple as splitting the <code>if (sb1 == null)</code>
+into two separate ifs, one for each local variable, which is a very small price to pay for the
+gain that now the compiler can exactly see what happens and check your code accordingly.
+More discussion on this topic will follow <a href="#tips_analyzable">below</a>.
+</p>
+<h3>Unchecked conversion from non-annotated type to @NonNull type</h3>
+<p>
+This group of problems is based on the following analogy: in a program using Java 5 generics
+any calls to pre-Java-5 libraries may expose raw types, i.e., applications of a generic type
+which fail to specify concrete type arguments. To fit such values into a program using
+generics the compiler can add an <i>implicit conversion</i> by assuming that type arguments were
+specified in the way expected by the client part of the code.
+The compiler will issue a warning about the use of such a conversion and proceed its type checking
+assuming the library "does the right thing".
+In exactly the same way, an un-annotated return type of a library method can be considered
+as a "raw" or "legacy" type.
+Again an <i>implicit conversion</i> can optimistically assume the expected specification.
+Again a warning is issued and analysis continues assuming that the library "does the right thing".
+</p>
+<p>
+Theoretically speaking, also the need for such implicit conversions indicates a specification
+violation. However, in this case it may be 3rd party code that violates the specification which our
+code expects. Or, maybe (as we have convinced ourselves of) some 3rd party code does fulfill the
+contract, but only fails to declare so (because it doesn't use null annotations).
+In such situations we may not be able to exactly fix the problem for <em>organizational</em> reasons.
+</p>
+<pre> @SuppressWarnings("null")
+ @NonNull Foo foo = Library.getFoo(); // implicit conversion
+ foo.bar();
+</pre>
+<p>
+The above code snippet assumes that <code>Library.getFoo()</code> returns a <code>Foo</code>
+without specifying a null annotation. We can integrate the return value into our annotated
+program by assignment to a <code>@NonNull</code> local variable, which triggers a warning
+regarding an unchecked conversion.
+By adding a corresponding <code>SuppressWarnings("null")</code> to this declaration
+we acknowledge the inherent danger and accept the responsibility of having verified that
+the library actually behaves as desired.
+</p>
+<h2 id="tips_analyzable">Tips for making code better analyzable</h2>
+<p>
+If flow analysis cannot see that a value is indeed not null, the simplest strategy is always
+to add a new scoped local variable annotated with <code>@NonNull</code>.
+Then, if you are convinced that the value assigned to this local will never be null at runtime you can use a helper methods like this:
+</p>
+<pre> static @NonNull <T> T assertNonNull(@Nullable T value, @Nullable String msg) {
+ if (value == null) throw new AssertionError(msg);
+ return value;
+ }
+ @NonNull MyType foo() {
+ if (isInitialized()) {
+ MyType couldBeNull = getObjectOrNull();
+ @NonNull MyType theValue = assertNonNull(couldBeNull,
+ "value should not be null because application " +
+ "is fully initialized at this point.");
+ return theValue;
+ }
+ return new MyTypeImpl();
+ }</pre>
+<p>
+Note that by using the above <code>assertNonNull()</code> method you are accepting the responsibility
+that this assertion will always hold at runtime.
+If that is not what you want, annotated local variables will still help to narrow down where and why the analysis
+sees a potential for null flowing into a certain location.
+</p>
+<h2 id="tips_adoption">Tips for adopting null annotations</h2>
+<p>
+At the time of releasing the JDT version 3.8.0, collecting advice for adopting null annotations is
+still work in progress. For that reason this information is currently maintained in the
+<a href="http://wiki.eclipse.org/JDT_Core/Null_Analysis/Adopting_Null_Annotations">Eclipse wiki</a>.
+</p>
+</body>
+</html>
diff --git a/bundles/org.eclipse.jdt.doc.user/tasks/task-using_null_type_annotations.htm b/bundles/org.eclipse.jdt.doc.user/tasks/task-using_null_type_annotations.htm
index 0cd3753..3f3cb87 100644
--- a/bundles/org.eclipse.jdt.doc.user/tasks/task-using_null_type_annotations.htm
+++ b/bundles/org.eclipse.jdt.doc.user/tasks/task-using_null_type_annotations.htm
@@ -1,555 +1,555 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
-<html lang="en">
-<head>
-<meta name="copyright" content="Copyright (c) GK Software AG and others 2014, 2015. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
-<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
-<meta http-equiv="Content-Style-Type" content="text/css">
-<link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type="text/css">
-<title>Using null type annotations</title>
-</head>
-<body>
-<h1> Using null type annotations </h1>
-<p>
-Starting with Java 8, null annotations can be used in a new and more powerful way,
-because the new concept of "type annotations" (JSR 308) supports the use of
-annotations as an extension to the type system.
-</p>
-<p>
-Technically, this is determined by two new elements in
-the enum <a href="http://docs.oracle.com/javase/8/docs/api/java/lang/annotation/ElementType.html"
- ><code>java.lang.annotation.ElementType</code></a>: <code>TYPE_USE</code> and
-<code>TYPE_PARAMETER</code>. Notably, when saying <code>@Target(ElementType.TYPE_USE)</code>
-the annotation thus marked can be attached basically to all usages of a type.
-</p>
-<p>
-By interpreting null annotations as part of the type system we interpret each
-class or interface <code>Cn</code> in the system as introducing two distinct types:
-"<code>@NonNull Cn</code>" and "<code>@Nullable Cn</code>".
-The former type contains all instances of <code>Cn</code> whereas the latter type
-additionally contains the value <code>null</code>.
-This implies that <code>@NonNull Cn</code> is a subtype of <code>@Nullable Cn</code>
-with all regular consequences regarding assignability.
-So ideally for every value in a program we will know if it can be null
-(and must be checked before dereference) or not.
-The un-annotated type will be considered a legacy type just like raw types are legacy
-types since the introduction of generics: a way for interfacing with old code,
-to be flagged with warnings about unchecked conversions.
-If we systematically avoid such legacy types, then the compiler can rigorously
-flag <em>every</em> unsafe usage.
-</p>
-<p>
-In order to achieve completeness of null analysis, checks regarding null type annotations
-have been integrated with all type checking tasks of the compiler (active if null annotations
-are enabled).
-</p>
-<p>
-Users <em>migrating</em> from null annotations in previous versions to Java-8-style
-null type annotations are advised to check the section about <a href="#compatibility">compatibility</a>.
-</p>
-<p>
-Note, that the actual qualified names of null type annotations are
-<a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#null_annotation_names">configurable</a>,
-but by default the ones shown here are used (from the package <code>org.eclipse.jdt.annotation</code>).
-When using 3rd party null annotation types, please ensure that those are properly defined using at least a <code>@Target</code>
-meta annotation, because otherwise the compiler can not distinguish between declaration annotations (Java 5)
-and type annotations (Java 8). Furthermore, some <a href="#compatibility_semantics">details of <code>@NonNullByDefault</code></a>
-are not supported when using 3rd party annotation types.
-</p>
-
-
-<h2 id="generics">Generics</h2>
-Perhaps the main advantage of type annotations for null analysis is the ability to annotate
-the parameters and arguments of generic classes and interfaces.
-Programmers only <em>using</em> generic classes may directly skip to the section on
-<a href="#typeArguments">type arguments</a> but designers of generic classes should
-take the time to understand the different implications of annotating these elements:
-<ul>
-<li><a href="#typeParameters">type parameters</a></li>
-<li><a href="#typeVariables">type variables</a></li>
-<li><a href="#typeArguments">type arguments</a></li>
-</ul>
-<h3 id="typeParameters">Type parameters</h3>
-<p>
-A generic class, interface or method may <em>declare</em> one or more type parameters.
-Technically these are declarations, and hence it was a mere oversight that these cannot
-be annotated in Java 5.
-In Java 8 an annotation can declare <code>@Target(ElementType.TYPE_PARAMETER)</code>
-to be applicable in this position. JDT's null type annotations
-<a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNull.html"><code>@NonNull</code></a> and
-<a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/Nullable.html"><code>@Nullable</code></a>
-are declared with
-<code>@Target({ TYPE_USE })</code>, which includes usage on type parameter declarations.
-</p>
-<p>
-With respect to null type annotations, each type parameter can be specified at one
-of these levels:
-</p>
-<dl>
-<dt><strong>unconstrained</strong></dt>
-<dd>the type parameter does not impose any nullness-constraints on the arguments that
- a client my substitute for the type parameter.</dd>
-<dt><strong>constrained by an upper bound</strong></dt>
-<dd>the type parameter has an <code>extends</code> clause that specifies
- minimal nullness-requirements on type arguments provided by clients</dd>
-<dt><strong>exactly specified</strong></dt>
-<dd>the type parameter restricts usage to types of exactly one particular nullness</dd>
-</dl>
-<p>
-Constraining a type parameter via an <strong>upper bound</strong> relies on the fact that each type
-'<code>@NonNull Cn</code>' is a subtype of the corresponding type '<code>@Nullable Cn</code>'.
-Hence, a <code>@Nullable</code> upper bound does not impose any restriction, whereas a
-<code>@NonNull</code> upper bound prohibits the substitution by a <code>@Nullable</code>
-type argument:
-<pre> // declarations:
- class C0<T0 extends @Nullable Object> {} // meaningless, no constraint imposed
- class C1<T1 extends @NonNull Object> {}
- ...
- // usage:
- C1<@NonNull String> c1String; // legal
- C1<@Nullable String> c1String; // illegal
-</pre>
-<p>
-For <strong>exact specification</strong> a null annotation may be attached to the type parameter
-declaration itself, which is interpreted as defining both an upper and a lower bound.
-In other words, only types with the exact same null type annotation are legal as type arguments:
-</p>
-<pre> // declaration:
- class C2<@Nullable T2> {}
- ...
- // usage:
- C2<@NonNull String> c2String; // illegal
- C2<@Nullable String> c2String; // legal
-</pre>
-<p>
-Given the asymmetry, that in Java a type parameter may declare only upper bounds but
-no lower bounds, the following three styles can be recommended:
-<ul>
-<li>Use a <code>@NonNull</code> upper bound for constraining type arguments to nonnull types.</li>
-<li>Directly specify a type parameter as <code>@Nullable</code> for constraining type arguments to nullable types.</li>
-<li>Use an unconstrained type parameter to support type arguments of either nullness.</li>
-</ul>
-<h3 id="typeVariables">Type variables</h3>
-<p>
-Within the scope of a generic declaration (class, interface or method), the name of a
-type parameter can be used as a <em>type variable</em>, i.e., a placeholder for a type
-that is not known at this point.
-</p>
-<p>
-A type variable will typically be used without (further) null annotations, which implies
-that the annotations from the type parameter declaration will apply as detailed below.
-In some situations, however, it is useful to annotate an individual use of a type variable.
-As an example consider the library method <code>java.util.Map.get(Object)</code>,
-which should actually be annotated like this:
-</p>
-<pre> @Nullable V get(Object key)</pre>
-<p>
-By this declaration we would indicate that the return type is <strong>the nullable variant
-of whatever type V may represent</strong>. In other words, a null annotation on the use
-of a type variable <em>overrides</em> any other null information that would otherwise
-apply to this type. In particular any null annotation on the corresponding type parameter
-declaration (or its bound) is overridden by a null annotation in this position.
-</p>
-<p>
-On the other hand, when using a type variable without immediate null annotations the following rules apply
-depending on the declaration of the corresponding type parameter:
-</p>
-<p>
-A type variable corresponding to a type parameter with a <strong><code>@NonNull</code> upper bound</strong>
-denotes a type that is <em>known to be nonnull</em>.
-</p>
-<pre> class C1<T1 extends @NonNull Number> {
- int consume(T1 t) {
- return t.intValue(); // OK since T1 is known to be nonnull
- }
- T1 provide() {
- return null; // NOT OK since T1 requires nonnull
- }
- }
-</pre>
-<p>
-A type variable corresponding to a type parameter <strong>specified as <code>@Nullable</code></strong>
-denotes a type that is <em>known to be nullable</em>.
-</p>
-<pre> class C2<@Nullable T2 extends Number> {
- int consume(T2 t) {
- return t.intValue(); // NOT OK since T2 is known to be nullable
- }
- T2 provide() {
- return null; // OK: returning null is legal
- }
- }
-</pre>
-<p id="pessimistic_analysis">
-A type variable corresponding to an <strong>unconstrained</strong> type parameter requires <strong>pessimistic
-checking</strong> in order to guarantee safety with all legal substitutions: this type can
-neither be assumed to be nullable nor nonnull.
-</p>
-<pre> class C<T extends Number> {
- int consume(T t) {
- return t.intValue(); // NOT OK since T could be nullable
- }
- T provide() {
- return null; // NOT OK since T could require nonnull
- }
- }
-</pre>
-<p>
-The last point may look surprising at first, but please see that an unconstrained type parameter
-implies that we may not assume anything about the nullness of the type represented by
-the corresponding type variable. Even more: we must actively support nullable <em>and</em>
-nonnull types. On the other hand this simply extends the existing rule that the only
-type being compatible with an unbounded type variable is the type variable itself.
-To explain this situation in the context of null analysis, the compiler will raise the
-following error against the return in <code>provide()</code>:
-</p>
-<blockquote>
-Null type mismatch (type annotations): 'null' is not compatible to the free type variable 'T'
-</blockquote>
-<p>The severity of problems detected by this pessimistic analysis is controlled by a dedicated <a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#pessimistic_analysis">preference option</a>.
-<p>
-By enforcing this defensive strategy regarding unconstrained type parameters we obtain the benefit
-of allowing clients to freely choose the rules for a particular generic instantiation,
-as will be shown next.
-</p>
-<h3 id="typeArguments">Type arguments</h3>
-<p>
-When instantiating a generic type or when invoking a generic method, the constraints put
-forward by the type parameter must be observed. Hence, when a provider of a generic type or method
-specified the required nullness, this must be obeyed and the compiler will flag any violations.
-</p>
-<p>
-When, on the other hand, a type parameter does not impose any restrictions, a client may
-freely choose the nullness of his type arguments:
-<pre>
- int processWithoutNulls (@NonNull List<<strong>@NonNull Integer</strong>> ints) {
- int result = 0;
- for (int i = 0; i < ints.size(); i++) {
- Integer element = ints.get(i);
- result += element.intValue(); // OK: list element is known to be nonnull
- ints.set(i, null); // NOT OK: list does not accept null value
- }
- return result;
- }
- int processWithNulls (@NonNull List<<strong>@Nullable Integer</strong>> ints) {
- int result = 0;
- for (int i = 0; i < ints.size(); i++) {
- Integer element = ints.get(i);
- result += element.intValue(); // NOT OK: list element can be null
- ints.set(i, null); // OK: list accepts null value
- }
- return result;
- }
-</pre>
-<h3 id="substitution">Substitution</h3>
-<p>
-The intention behind combining null type annotations with generics is to propagate a constraint defined for a type argument
-into all occurrences of the corresponding type variable. For example, if you declare a variable of type <code>List<@NonNull String></code>
-and invoke any method from <code>List<T></code> on this variable, all method signatures will see type <code>T</code> substituted by <code>@NonNull String</code>.
-This is how inserting a <code>null</code> value into this list is made impossible, and allows to safely regard elements extracted from this list as nonnull.
-The previous section gave examples of exactly this idea.
-</p>
-<p>
-Unfortunately, this idea introduces a new risk when applied to generic library classes that are <em>not designed with null annotations in mind.</em>
-A prominent example is method <code>java.util.Map.get(K)</code>, which declares to return <code>V</code>.
-In this particular case, the javadoc of said method explicitly states that <code>null</code> is a possible return value,
-which is in conflict with substituting <code>V</code> by any nonnull type.
-So, if this specific method <code>get()</code> is invoked on a variable of type <code>Map<Y,@NonNull X></code>,
-it is <em>unsafe</em> to assume that the return value is nonnull.
-This dilemma is a combination of two factors:
-</p>
-<ol>
-<li>The library lacks null annotations (it should be considered as "legacy" in terms of null annotations)</li>
-<li>The compiler cannot know whether an unannotated type variable is by intention (as to support arbitrary substitution) or an unsafe omission (legacy).
-</ol>
-<p>
-To alert users about this risk, a specific warning is raised by the compiler:
-</p>
-<blockquote>
-Unsafe interpretation of method return type as '@NonNull X' based on the receiver type 'Map<Y,@NonNull X>'. Type 'Map' doesn't seem to be designed with null type annotations in mind
-</blockquote>
-<p>The severity of this problem is controlled by a dedicated <a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#unsafe_interpretation_generic_legacy">preference option</a>.
-<p>In response to this warning, the resolution of the dilemma is to add null annotations to the generic class in question.
-For the likely case that the current user is not the owner of the legacy library,
-<a href="task-using_external_null_annotations.htm">external null annotations</a> should be used.
-Then there are two options:</p>
-<ol>
-<li>For the given example, method <code>get(K)</code> should be declared to return <code>@Nullable V</code>.
- </li>
-<li>For the opposite case as exemplified by <code>List.get()</code>, the return type should be left unannotated.
- In order to signal to the compiler that types are left <em>unannotated by intention</em>,
- a stub external annotation file (.eea) should be created without inserting actual external annotations.
- This will tell the compiler that this class is no longer to be considered as legacy,
- and hence all signatures of this class should be interpreted verbatim according to the rules given above
- (care must be taken that this is safe for all method in that class).
- </li>
-</ol>
-<p>If an external annotation file is found, the specific warning about unsafe interpretation is not issued.
-Finally, if a project is not yet configured for using external annotations for the given library,
-the problem is softened to "info" severity.
-</p>
-
-<h2 id="inference">Inference</h2>
-<p>
-With null type annotations affecting type arguments, the language features one
-more location amenable to inference: during type inference for the invocation
-of a generic method (lambda expression etc.), type inference shyly attempts to
-also infer the appropriate null type annotations. Example:
-</p>
-<pre> <T> T check(T in) { return in; }
- void test(@NonNull List<@Nullable String> someStrings) {
- @NonNull List<@Nullable String> checked;
- checked = check(someStrings); // inferring types for this invocation
- ...
- }
-</pre>
-<p>
-In this trivial example, inference will indeed instantiate the generic parameter <code><T></code>
-to <code>@NonNull List<@Nullable String></code>. More complex scenarios are inferred, too,
-but no guarantee is made, that a possible solution will always be found. In case inference fails
-to infer suitable null type annotations, users are advised to revert to explicitly specify
-type arguments even of a generic method invocation.
-</p>
-
-<h2 id="more_locations">More locations</h2>
-<h3>Cast and instanceof</h3>
-<p>
-Syntactically, type annotations can be used also in casts and instanceof expressions.
-For null annotations, however, this has limited value.
-</p>
-<p>
-<strong>Casting</strong> to a null-annotated type is always an <em>unchecked cast</em> because the
-compiler is not allowed to insert runtime checks that would make the cast meaningful.
-If a runtime check is desired, please consider using a small helper function like:
-</p>
-<pre> static @NonNull <T> T castToNonNull(@Nullable T value, @Nullable String msg) {
- if (value == null) throw new NullPointerException(msg);
- return value;
- }
-</pre>
-<p>
-Casts affecting the type arguments of a generic type will always be unchecked casts due to erasure.
-</p>
-<p>
-<strong>instanceof</strong> checks with null type annotations are not meaningful.
-Hence the compiler flags this as illegal usage of a null type annotation.
-</p>
-<h3>Locations that are nonnull by definition</h3>
-<p>
-Syntactically, type annotations can also be used for
-</p>
-<ul>
-<li>allocation expressions</li>
-<li>method receiver (pseudo argument by the name of <strong>this</strong>)</li>
-<li>catch parameter</li>
-</ul>
-<p>
-In each of these constructs, the type is nonnull by definition.
-Hence a null type annotation in one of these positions is flagged as illegal use.
-This doesn't, however, restrict the use of null type annotations on type arguments
-of the given type.
-</p>
-
-<h2 id="compatibility">Compatibility</h2>
-<p>
-Migrating from declaration annotations to type annotations has a few unavoidable
-implications, regarding the syntax, regarding project configuration and regarding
-the semantics.
-</p>
-<h3 id="compatibility_syntax">Syntax</h3>
-<p>
-For two constructs the JLS introduces a syntactic change:
-</p>
-<table border="1" cellspacing="0" cellpadding="5" summary="Syntax Changes">
-<tr><th>Declaration Annotations (Java 7 or below)</th><th>Type Annotation (Java 8)</th></tr>
-<tr><td><code>@NonNull String[]</code></td><td><code>String @NonNull[]</code></td></tr>
-<tr><td><code>@NonNull java.lang.String</code></td><td><code>java.lang.@NonNull String</code></td></tr>
-</table>
-<p>
-In both cases the new syntax has been introduced to provide more options.
-</p>
-<p>
-For <strong>arrays</strong> a type annotation before the leaf element type will now denote
-an array whose individual cells have the given nullness - here: cells cannot be null.
-In Java 7 and below the same syntax expressed a property of the corresponding variable
-and hence captured the nullness of the array itself.
-To express the same using Java-8 type annotations, viz. that the array itself can or cannot be null,
-the type annotation is placed before the square brackets denoting the array dimensions.
-This implies that the old syntax is still valid, but its meaning has changed:
-</p>
-<pre>
- // annotated leaf type:
- @NonNull Object [] o1;
- o1 = null; // OK
- o1 = new Object[1];
- o1[0] = null; // NOT OK
- ...
- // annotated array type:
- Object @NonNull[] o2;
- o2 = null; // NOT OK
- o2 = new Object[1];
- o2[0] = null; // OK
- ...
- // multi-dimensional array:
- Object @NonNull[] @Nullable[] o3;
- o3 = null; // NOT OK, outer array is nonnull
- o3 = new Object[1] @Nullable[];
- o3[0] = null; // OK, inner array is nullable
-</pre>
-<p>
-Unfortunately, checking proper initialization of an array with nonnull content
-is beyond the capabilities of JDT's static analysis.
-</p>
-<p>
-For <strong>qualified type names</strong> the type annotation must be placed directly preceding the
-actual type name. This way it is possible to give different type annotations for
-inner classes and their enclosing like in <code>org.project.@Immutable Outer.@Nullable Inner</code>.
-This distinction, however, is not useful for null annotations, because the enclosing
-of a non-static inner class is by definition always non-null. Users of null type
-annotations only need to understand that the old syntax for this case is illegal
-for type annotations and how to convert this into legal Java 8 code (see the table above).
-</p>
-<h3 id="compatibility_configuration">Project configuration</h3>
-<p>
-Properly designed annotation types can be distinguished by looking at their <code>@Target</code>
-declaration (the use of null annotations lacking a <code>@Target</code> declaration is discouraged).
-To support both styles of annotations, JDT has published a major update of the annotation
-bundle <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/package-summary.html"><code>org.eclipse.jdt.annotation</code></a>:
-Versions 1.1.x are old style declaration annotations; versions 2.0.0 and onward are type annotations.
-By increasing the major version an incompatibility is signaled. Users are advised to
-reference this library with an explicit version range, either <code>[1.1.0,2.0.0)</code>
-for declaration annotations or <code>[2.0.0,3.0.0)</code> for type annotations.
-</p>
-<p>
-The exact configuration depends of course on the flavor of project:
-<dl>
-<dt>Plain Java</dt>
-<dd>JDT continues to offer a quickfix for copying the annotation library into the
-project. The version will be determined by the compliance settings of the project.</dd>
-<dt>Maven</dt>
-<dd>Both versions of the annotation bundle will be published to <code>repo.eclipse.org</code>,
-from where they can be consumed using the regular maven mechanisms: be sure to specify
-the correct version; specifying <code><scope>compile</scope></code> is recommended
-for this dependency.</dd>
-<dt>OSGi / Eclipse</dt>
-<dd>When developing OSGi bundles / Eclipse plugins the version range should be specified as
-mentioned above. Unfortunately, OSGi doesn't support a concept of compile time dependencies.
-The PDE specific mechanism in file <code>build.properties</code> is problematic because
-it doesn't support specifying a version range. Thus the best approximation of the desired
-semantics is to use a <code>Require-Bundle</code> dependency.
-qualified with <code>resolution:=optional</code> in order to avoid forcing this dependency
-on the runtime:
-<pre>
-Require-Bundle: ...,
- org.eclipse.jdt.annotation;bundle-version="[2.0.0,3.0.0)";resolution:=optional
-</pre></dd>
-</dl>
-<h3 id="compatibility_semantics">Semantics – NonNullByDefault</h3>
-<p>
-While the fundamental semantics of null annotation remains unchanged,
-the annotation <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNullByDefault.html"
- ><code>@NonNullByDefault</code></a> has been changed slightly:
-</p>
-<ul>
-<li>This annotation can now affect more locations.</li>
-<li>The locations to be affected can be fine tuned using the
-<a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNullByDefault.html#value--"
- ><code>value</code></a> property of the annotation
- (see also the enum <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/DefaultLocation.html"
- ><code>DefaultLocation</code></a>).</li>
-<li>As a consequence, the notation for canceling a default from an outer scope has been changed, too:
-<table border="1" cellspacing="0" cellpadding="5" summary="Cancelling a default">
-<tr><th>Declaration Annotations (Java 7 or below)</th><th>Type Annotation (Java 8)</th></tr>
-<tr><td><code>@NonNullByDefault(false)</code></td><td><code>@NonNullByDefault({})</code></td></tr>
-</table>
-</li>
-</ul>
-<p>
-Note, that the <code>value</code> property described here is only supported when using the annotation type
-<code>org.eclipse.jdt.annotation.NonNullByDefault</code> supplied by Eclipse.
-</p>
-<p>
-Although the Java 8 variant of
- <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNullByDefault.html"
- ><code>@NonNullByDefault</code></a> affects more locations, two noteworthy exceptions exist
- (as specified in <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/DefaultLocation.html"
- ><code>DefaultLocation</code></a>):
-<blockquote>
- <strong>
- Wildcards and the use of type variables are always excluded from
- <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNullByDefault.html"
- ><code>@NonNullByDefault</code></a>.
- </strong>
-</blockquote>
-<p>
-By this rule, type variables and wildcards retain their intended properties as "unknowns" also in terms of nullness,
-even when they appear in the context of
- <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNullByDefault.html"
- ><code>@NonNullByDefault</code></a>.
-</p>
-
-<h2 id="compiler_messages_explained">Compiler messages explained</h2>
-<p>
-In addition to
-<a href="PLUGINS_ROOT/org.eclipse.jdt.doc.user/tasks/task-using_null_annotations.htm#compiler_messages_explained"
->compiler messages of the previous version</a> the following messages may be issued,
-if null type annotations are enabled for analysis:
-</p>
-
-<h3>General null type mismatch</h3>
-<dl>
-<dt><font color="SaddleBrown">Null type mismatch (type annotations): required 'X' but this expression has type 'Y'</font></dt>
-<dd>In an assignment context null type annotations don't match.
- Note that the mismatch may relate to any detail of the type (type argument, array element), not necessarily to the main type.</dd>
-</dl>
-<p>
-All mismatches detected based on type annotations are prefixed with "<code>Null type mismatch (type annotations)</code>".
-</p>
-
-<h3>Various expressions</h3>
-<dl>
-<dt><font color="SaddleBrown">Potential null pointer access: array element may be null</font></dt>
-<dd>An array element is dereferenced, where the array type declares its elements as <code>@Nullable</code>.</dd>
-<dt><font color="SaddleBrown">Potential null pointer access: this expression has a '@Nullable' type</font></dt>
-<dd>Any expression at the left hand side of a dot has a type that is declared to be nullable.</dd>
-<dt><font color="SaddleBrown">Redundant null check: comparing '@NonNull X' against null</font></dt>
-<dd>An arbitrary expression known to have a @NonNull type is unnecessarily being compared against null.</dd>
-</dl>
-
-<h3>Unchecked conversions</h3>
-<dl>
-<dt><font color="SaddleBrown">Null type safety (type annotations): The expression of type 'X' needs unchecked conversion to conform to '@NonNull X'</font></dt>
-<dd>A value of an un-annotated type is being assigned to a variable of an annotated type.
- Note that the mismatch may relate to any detail of the type (type argument, array element), not necessarily to the main type.</dd>
-<dt><font color="SaddleBrown">Null type safety: Unchecked cast from X to '@N Y'</font></dt>
-<dd>A value is casted to a null-annotated type, where the nullness is not checked at runtime by the cast.</dd>
-</dl>
-
-<h3>Problems specific to generics</h3>
-<dl>
-<dt><font color="SaddleBrown">Null constraint mismatch: The type 'X' is not a valid substitute for the type parameter 'T'</font></dt>
-<dd>Here the type parameter <code><T></code> has a constraint in one of the forms mentioned <a href="#typeParameters">above</a>.
- The actual type argument <code>X</code>, however, doesn't conform to this constraint.</dd>
-<dt><font color="SaddleBrown">This nullness annotation conflicts with a '@N' annotation which is effective on the same type parameter</font></dt>
-<dd>A null annotation on a bound of a type parameter conflicts with another null annotation on another bound or on the type parameter itself.</dd>
-<dt><font color="SaddleBrown">Contradictory null annotations: method was inferred as 'T foo(X)', but only one of '@NonNull' and '@Nullable' can be effective at any location</font></dt>
-<dd>Type inference for a generic method invocation has produced a signature in which contradictory null annotations clash on the same element.<dd>
-<dt><font color="SaddleBrown">Null type mismatch (type annotations): 'null' is not compatible to the free type variable 'T'</font></dt>
-<dt><font color="SaddleBrown">Null type mismatch (type annotations): required 'T' but this expression has type '@Nullable T', where 'T' is a free type variable</font></dt>
-<dt><font color="SaddleBrown">Null type safety: required '@NonNull' but this expression has type 'T', a free type variable that may represent a '@Nullable' type</font></dt>
-<dt><font color="SaddleBrown">The field 'f' may not have been initialized, whereas its type 'T' is a free type variable that may represent a '@NonNull' type</font></dt>
-<dt><font color="SaddleBrown">Potential null pointer access: this expression has type 'T', a free type variable that may represent a '@Nullable' type</font></dt>
-<dd>These problems are specifically detected by <a href="#pessimistic_analysis">pessimistic analysis for free type variables</a>.</dd>
-<dt><font color="SaddleBrown">Unsafe interpretation of method return type as '@NonNull X' based on the receiver type 'Map<Y,@NonNull X>'. Type 'Map' doesn't seem to be designed with null type annotations in mind</font></dt>
-<dt><font color="SaddleBrown">Unsafe interpretation of method return type as '@NonNull X' based on substitution 'V=@NonNull X'. Declaring type 'Map<K,V>' doesn't seem to be designed with null type annotations in mind</font></dt>
-<dd>This signals a particular dilemma regarding <a href="#substitution">substitution of type variables from a legacy library</a>.
-</dl>
-
-
-<h3>Lambda expressions and method references</h3>
-For any mismatches in null annotations affecting lambda expressions or method references the corresponding
-"descriptor" is mentioned (the single abstract method being implemented by the lambda / method reference).
-This is useful for finding the origin of a null annotation that is not explicit at the current expression.
-
-
-</body>
-</html>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html lang="en">
+<head>
+<meta name="copyright" content="Copyright (c) GK Software AG and others 2014, 2015. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<link rel="stylesheet" href="../book.css" charset="ISO-8859-1" type="text/css">
+<title>Using null type annotations</title>
+</head>
+<body>
+<h1> Using null type annotations </h1>
+<p>
+Starting with Java 8, null annotations can be used in a new and more powerful way,
+because the new concept of "type annotations" (JSR 308) supports the use of
+annotations as an extension to the type system.
+</p>
+<p>
+Technically, this is determined by two new elements in
+the enum <a href="http://docs.oracle.com/javase/8/docs/api/java/lang/annotation/ElementType.html"
+ ><code>java.lang.annotation.ElementType</code></a>: <code>TYPE_USE</code> and
+<code>TYPE_PARAMETER</code>. Notably, when saying <code>@Target(ElementType.TYPE_USE)</code>
+the annotation thus marked can be attached basically to all usages of a type.
+</p>
+<p>
+By interpreting null annotations as part of the type system we interpret each
+class or interface <code>Cn</code> in the system as introducing two distinct types:
+"<code>@NonNull Cn</code>" and "<code>@Nullable Cn</code>".
+The former type contains all instances of <code>Cn</code> whereas the latter type
+additionally contains the value <code>null</code>.
+This implies that <code>@NonNull Cn</code> is a subtype of <code>@Nullable Cn</code>
+with all regular consequences regarding assignability.
+So ideally for every value in a program we will know if it can be null
+(and must be checked before dereference) or not.
+The un-annotated type will be considered a legacy type just like raw types are legacy
+types since the introduction of generics: a way for interfacing with old code,
+to be flagged with warnings about unchecked conversions.
+If we systematically avoid such legacy types, then the compiler can rigorously
+flag <em>every</em> unsafe usage.
+</p>
+<p>
+In order to achieve completeness of null analysis, checks regarding null type annotations
+have been integrated with all type checking tasks of the compiler (active if null annotations
+are enabled).
+</p>
+<p>
+Users <em>migrating</em> from null annotations in previous versions to Java-8-style
+null type annotations are advised to check the section about <a href="#compatibility">compatibility</a>.
+</p>
+<p>
+Note, that the actual qualified names of null type annotations are
+<a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#null_annotation_names">configurable</a>,
+but by default the ones shown here are used (from the package <code>org.eclipse.jdt.annotation</code>).
+When using 3rd party null annotation types, please ensure that those are properly defined using at least a <code>@Target</code>
+meta annotation, because otherwise the compiler can not distinguish between declaration annotations (Java 5)
+and type annotations (Java 8). Furthermore, some <a href="#compatibility_semantics">details of <code>@NonNullByDefault</code></a>
+are not supported when using 3rd party annotation types.
+</p>
+
+
+<h2 id="generics">Generics</h2>
+Perhaps the main advantage of type annotations for null analysis is the ability to annotate
+the parameters and arguments of generic classes and interfaces.
+Programmers only <em>using</em> generic classes may directly skip to the section on
+<a href="#typeArguments">type arguments</a> but designers of generic classes should
+take the time to understand the different implications of annotating these elements:
+<ul>
+<li><a href="#typeParameters">type parameters</a></li>
+<li><a href="#typeVariables">type variables</a></li>
+<li><a href="#typeArguments">type arguments</a></li>
+</ul>
+<h3 id="typeParameters">Type parameters</h3>
+<p>
+A generic class, interface or method may <em>declare</em> one or more type parameters.
+Technically these are declarations, and hence it was a mere oversight that these cannot
+be annotated in Java 5.
+In Java 8 an annotation can declare <code>@Target(ElementType.TYPE_PARAMETER)</code>
+to be applicable in this position. JDT's null type annotations
+<a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNull.html"><code>@NonNull</code></a> and
+<a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/Nullable.html"><code>@Nullable</code></a>
+are declared with
+<code>@Target({ TYPE_USE })</code>, which includes usage on type parameter declarations.
+</p>
+<p>
+With respect to null type annotations, each type parameter can be specified at one
+of these levels:
+</p>
+<dl>
+<dt><strong>unconstrained</strong></dt>
+<dd>the type parameter does not impose any nullness-constraints on the arguments that
+ a client my substitute for the type parameter.</dd>
+<dt><strong>constrained by an upper bound</strong></dt>
+<dd>the type parameter has an <code>extends</code> clause that specifies
+ minimal nullness-requirements on type arguments provided by clients</dd>
+<dt><strong>exactly specified</strong></dt>
+<dd>the type parameter restricts usage to types of exactly one particular nullness</dd>
+</dl>
+<p>
+Constraining a type parameter via an <strong>upper bound</strong> relies on the fact that each type
+'<code>@NonNull Cn</code>' is a subtype of the corresponding type '<code>@Nullable Cn</code>'.
+Hence, a <code>@Nullable</code> upper bound does not impose any restriction, whereas a
+<code>@NonNull</code> upper bound prohibits the substitution by a <code>@Nullable</code>
+type argument:
+<pre> // declarations:
+ class C0<T0 extends @Nullable Object> {} // meaningless, no constraint imposed
+ class C1<T1 extends @NonNull Object> {}
+ ...
+ // usage:
+ C1<@NonNull String> c1String; // legal
+ C1<@Nullable String> c1String; // illegal
+</pre>
+<p>
+For <strong>exact specification</strong> a null annotation may be attached to the type parameter
+declaration itself, which is interpreted as defining both an upper and a lower bound.
+In other words, only types with the exact same null type annotation are legal as type arguments:
+</p>
+<pre> // declaration:
+ class C2<@Nullable T2> {}
+ ...
+ // usage:
+ C2<@NonNull String> c2String; // illegal
+ C2<@Nullable String> c2String; // legal
+</pre>
+<p>
+Given the asymmetry, that in Java a type parameter may declare only upper bounds but
+no lower bounds, the following three styles can be recommended:
+<ul>
+<li>Use a <code>@NonNull</code> upper bound for constraining type arguments to nonnull types.</li>
+<li>Directly specify a type parameter as <code>@Nullable</code> for constraining type arguments to nullable types.</li>
+<li>Use an unconstrained type parameter to support type arguments of either nullness.</li>
+</ul>
+<h3 id="typeVariables">Type variables</h3>
+<p>
+Within the scope of a generic declaration (class, interface or method), the name of a
+type parameter can be used as a <em>type variable</em>, i.e., a placeholder for a type
+that is not known at this point.
+</p>
+<p>
+A type variable will typically be used without (further) null annotations, which implies
+that the annotations from the type parameter declaration will apply as detailed below.
+In some situations, however, it is useful to annotate an individual use of a type variable.
+As an example consider the library method <code>java.util.Map.get(Object)</code>,
+which should actually be annotated like this:
+</p>
+<pre> @Nullable V get(Object key)</pre>
+<p>
+By this declaration we would indicate that the return type is <strong>the nullable variant
+of whatever type V may represent</strong>. In other words, a null annotation on the use
+of a type variable <em>overrides</em> any other null information that would otherwise
+apply to this type. In particular any null annotation on the corresponding type parameter
+declaration (or its bound) is overridden by a null annotation in this position.
+</p>
+<p>
+On the other hand, when using a type variable without immediate null annotations the following rules apply
+depending on the declaration of the corresponding type parameter:
+</p>
+<p>
+A type variable corresponding to a type parameter with a <strong><code>@NonNull</code> upper bound</strong>
+denotes a type that is <em>known to be nonnull</em>.
+</p>
+<pre> class C1<T1 extends @NonNull Number> {
+ int consume(T1 t) {
+ return t.intValue(); // OK since T1 is known to be nonnull
+ }
+ T1 provide() {
+ return null; // NOT OK since T1 requires nonnull
+ }
+ }
+</pre>
+<p>
+A type variable corresponding to a type parameter <strong>specified as <code>@Nullable</code></strong>
+denotes a type that is <em>known to be nullable</em>.
+</p>
+<pre> class C2<@Nullable T2 extends Number> {
+ int consume(T2 t) {
+ return t.intValue(); // NOT OK since T2 is known to be nullable
+ }
+ T2 provide() {
+ return null; // OK: returning null is legal
+ }
+ }
+</pre>
+<p id="pessimistic_analysis">
+A type variable corresponding to an <strong>unconstrained</strong> type parameter requires <strong>pessimistic
+checking</strong> in order to guarantee safety with all legal substitutions: this type can
+neither be assumed to be nullable nor nonnull.
+</p>
+<pre> class C<T extends Number> {
+ int consume(T t) {
+ return t.intValue(); // NOT OK since T could be nullable
+ }
+ T provide() {
+ return null; // NOT OK since T could require nonnull
+ }
+ }
+</pre>
+<p>
+The last point may look surprising at first, but please see that an unconstrained type parameter
+implies that we may not assume anything about the nullness of the type represented by
+the corresponding type variable. Even more: we must actively support nullable <em>and</em>
+nonnull types. On the other hand this simply extends the existing rule that the only
+type being compatible with an unbounded type variable is the type variable itself.
+To explain this situation in the context of null analysis, the compiler will raise the
+following error against the return in <code>provide()</code>:
+</p>
+<blockquote>
+Null type mismatch (type annotations): 'null' is not compatible to the free type variable 'T'
+</blockquote>
+<p>The severity of problems detected by this pessimistic analysis is controlled by a dedicated <a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#pessimistic_analysis">preference option</a>.
+<p>
+By enforcing this defensive strategy regarding unconstrained type parameters we obtain the benefit
+of allowing clients to freely choose the rules for a particular generic instantiation,
+as will be shown next.
+</p>
+<h3 id="typeArguments">Type arguments</h3>
+<p>
+When instantiating a generic type or when invoking a generic method, the constraints put
+forward by the type parameter must be observed. Hence, when a provider of a generic type or method
+specified the required nullness, this must be obeyed and the compiler will flag any violations.
+</p>
+<p>
+When, on the other hand, a type parameter does not impose any restrictions, a client may
+freely choose the nullness of his type arguments:
+<pre>
+ int processWithoutNulls (@NonNull List<<strong>@NonNull Integer</strong>> ints) {
+ int result = 0;
+ for (int i = 0; i < ints.size(); i++) {
+ Integer element = ints.get(i);
+ result += element.intValue(); // OK: list element is known to be nonnull
+ ints.set(i, null); // NOT OK: list does not accept null value
+ }
+ return result;
+ }
+ int processWithNulls (@NonNull List<<strong>@Nullable Integer</strong>> ints) {
+ int result = 0;
+ for (int i = 0; i < ints.size(); i++) {
+ Integer element = ints.get(i);
+ result += element.intValue(); // NOT OK: list element can be null
+ ints.set(i, null); // OK: list accepts null value
+ }
+ return result;
+ }
+</pre>
+<h3 id="substitution">Substitution</h3>
+<p>
+The intention behind combining null type annotations with generics is to propagate a constraint defined for a type argument
+into all occurrences of the corresponding type variable. For example, if you declare a variable of type <code>List<@NonNull String></code>
+and invoke any method from <code>List<T></code> on this variable, all method signatures will see type <code>T</code> substituted by <code>@NonNull String</code>.
+This is how inserting a <code>null</code> value into this list is made impossible, and allows to safely regard elements extracted from this list as nonnull.
+The previous section gave examples of exactly this idea.
+</p>
+<p>
+Unfortunately, this idea introduces a new risk when applied to generic library classes that are <em>not designed with null annotations in mind.</em>
+A prominent example is method <code>java.util.Map.get(K)</code>, which declares to return <code>V</code>.
+In this particular case, the javadoc of said method explicitly states that <code>null</code> is a possible return value,
+which is in conflict with substituting <code>V</code> by any nonnull type.
+So, if this specific method <code>get()</code> is invoked on a variable of type <code>Map<Y,@NonNull X></code>,
+it is <em>unsafe</em> to assume that the return value is nonnull.
+This dilemma is a combination of two factors:
+</p>
+<ol>
+<li>The library lacks null annotations (it should be considered as "legacy" in terms of null annotations)</li>
+<li>The compiler cannot know whether an unannotated type variable is by intention (as to support arbitrary substitution) or an unsafe omission (legacy).
+</ol>
+<p>
+To alert users about this risk, a specific warning is raised by the compiler:
+</p>
+<blockquote>
+Unsafe interpretation of method return type as '@NonNull X' based on the receiver type 'Map<Y,@NonNull X>'. Type 'Map' doesn't seem to be designed with null type annotations in mind
+</blockquote>
+<p>The severity of this problem is controlled by a dedicated <a href="../reference/preferences/java/compiler/ref-preferences-errors-warnings.htm#unsafe_interpretation_generic_legacy">preference option</a>.
+<p>In response to this warning, the resolution of the dilemma is to add null annotations to the generic class in question.
+For the likely case that the current user is not the owner of the legacy library,
+<a href="task-using_external_null_annotations.htm">external null annotations</a> should be used.
+Then there are two options:</p>
+<ol>
+<li>For the given example, method <code>get(K)</code> should be declared to return <code>@Nullable V</code>.
+ </li>
+<li>For the opposite case as exemplified by <code>List.get()</code>, the return type should be left unannotated.
+ In order to signal to the compiler that types are left <em>unannotated by intention</em>,
+ a stub external annotation file (.eea) should be created without inserting actual external annotations.
+ This will tell the compiler that this class is no longer to be considered as legacy,
+ and hence all signatures of this class should be interpreted verbatim according to the rules given above
+ (care must be taken that this is safe for all method in that class).
+ </li>
+</ol>
+<p>If an external annotation file is found, the specific warning about unsafe interpretation is not issued.
+Finally, if a project is not yet configured for using external annotations for the given library,
+the problem is softened to "info" severity.
+</p>
+
+<h2 id="inference">Inference</h2>
+<p>
+With null type annotations affecting type arguments, the language features one
+more location amenable to inference: during type inference for the invocation
+of a generic method (lambda expression etc.), type inference shyly attempts to
+also infer the appropriate null type annotations. Example:
+</p>
+<pre> <T> T check(T in) { return in; }
+ void test(@NonNull List<@Nullable String> someStrings) {
+ @NonNull List<@Nullable String> checked;
+ checked = check(someStrings); // inferring types for this invocation
+ ...
+ }
+</pre>
+<p>
+In this trivial example, inference will indeed instantiate the generic parameter <code><T></code>
+to <code>@NonNull List<@Nullable String></code>. More complex scenarios are inferred, too,
+but no guarantee is made, that a possible solution will always be found. In case inference fails
+to infer suitable null type annotations, users are advised to revert to explicitly specify
+type arguments even of a generic method invocation.
+</p>
+
+<h2 id="more_locations">More locations</h2>
+<h3>Cast and instanceof</h3>
+<p>
+Syntactically, type annotations can be used also in casts and instanceof expressions.
+For null annotations, however, this has limited value.
+</p>
+<p>
+<strong>Casting</strong> to a null-annotated type is always an <em>unchecked cast</em> because the
+compiler is not allowed to insert runtime checks that would make the cast meaningful.
+If a runtime check is desired, please consider using a small helper function like:
+</p>
+<pre> static @NonNull <T> T castToNonNull(@Nullable T value, @Nullable String msg) {
+ if (value == null) throw new NullPointerException(msg);
+ return value;
+ }
+</pre>
+<p>
+Casts affecting the type arguments of a generic type will always be unchecked casts due to erasure.
+</p>
+<p>
+<strong>instanceof</strong> checks with null type annotations are not meaningful.
+Hence the compiler flags this as illegal usage of a null type annotation.
+</p>
+<h3>Locations that are nonnull by definition</h3>
+<p>
+Syntactically, type annotations can also be used for
+</p>
+<ul>
+<li>allocation expressions</li>
+<li>method receiver (pseudo argument by the name of <strong>this</strong>)</li>
+<li>catch parameter</li>
+</ul>
+<p>
+In each of these constructs, the type is nonnull by definition.
+Hence a null type annotation in one of these positions is flagged as illegal use.
+This doesn't, however, restrict the use of null type annotations on type arguments
+of the given type.
+</p>
+
+<h2 id="compatibility">Compatibility</h2>
+<p>
+Migrating from declaration annotations to type annotations has a few unavoidable
+implications, regarding the syntax, regarding project configuration and regarding
+the semantics.
+</p>
+<h3 id="compatibility_syntax">Syntax</h3>
+<p>
+For two constructs the JLS introduces a syntactic change:
+</p>
+<table border="1" cellspacing="0" cellpadding="5" summary="Syntax Changes">
+<tr><th>Declaration Annotations (Java 7 or below)</th><th>Type Annotation (Java 8)</th></tr>
+<tr><td><code>@NonNull String[]</code></td><td><code>String @NonNull[]</code></td></tr>
+<tr><td><code>@NonNull java.lang.String</code></td><td><code>java.lang.@NonNull String</code></td></tr>
+</table>
+<p>
+In both cases the new syntax has been introduced to provide more options.
+</p>
+<p>
+For <strong>arrays</strong> a type annotation before the leaf element type will now denote
+an array whose individual cells have the given nullness - here: cells cannot be null.
+In Java 7 and below the same syntax expressed a property of the corresponding variable
+and hence captured the nullness of the array itself.
+To express the same using Java-8 type annotations, viz. that the array itself can or cannot be null,
+the type annotation is placed before the square brackets denoting the array dimensions.
+This implies that the old syntax is still valid, but its meaning has changed:
+</p>
+<pre>
+ // annotated leaf type:
+ @NonNull Object [] o1;
+ o1 = null; // OK
+ o1 = new Object[1];
+ o1[0] = null; // NOT OK
+ ...
+ // annotated array type:
+ Object @NonNull[] o2;
+ o2 = null; // NOT OK
+ o2 = new Object[1];
+ o2[0] = null; // OK
+ ...
+ // multi-dimensional array:
+ Object @NonNull[] @Nullable[] o3;
+ o3 = null; // NOT OK, outer array is nonnull
+ o3 = new Object[1] @Nullable[];
+ o3[0] = null; // OK, inner array is nullable
+</pre>
+<p>
+Unfortunately, checking proper initialization of an array with nonnull content
+is beyond the capabilities of JDT's static analysis.
+</p>
+<p>
+For <strong>qualified type names</strong> the type annotation must be placed directly preceding the
+actual type name. This way it is possible to give different type annotations for
+inner classes and their enclosing like in <code>org.project.@Immutable Outer.@Nullable Inner</code>.
+This distinction, however, is not useful for null annotations, because the enclosing
+of a non-static inner class is by definition always non-null. Users of null type
+annotations only need to understand that the old syntax for this case is illegal
+for type annotations and how to convert this into legal Java 8 code (see the table above).
+</p>
+<h3 id="compatibility_configuration">Project configuration</h3>
+<p>
+Properly designed annotation types can be distinguished by looking at their <code>@Target</code>
+declaration (the use of null annotations lacking a <code>@Target</code> declaration is discouraged).
+To support both styles of annotations, JDT has published a major update of the annotation
+bundle <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/package-summary.html"><code>org.eclipse.jdt.annotation</code></a>:
+Versions 1.1.x are old style declaration annotations; versions 2.0.0 and onward are type annotations.
+By increasing the major version an incompatibility is signaled. Users are advised to
+reference this library with an explicit version range, either <code>[1.1.0,2.0.0)</code>
+for declaration annotations or <code>[2.0.0,3.0.0)</code> for type annotations.
+</p>
+<p>
+The exact configuration depends of course on the flavor of project:
+<dl>
+<dt>Plain Java</dt>
+<dd>JDT continues to offer a quickfix for copying the annotation library into the
+project. The version will be determined by the compliance settings of the project.</dd>
+<dt>Maven</dt>
+<dd>Both versions of the annotation bundle will be published to <code>repo.eclipse.org</code>,
+from where they can be consumed using the regular maven mechanisms: be sure to specify
+the correct version; specifying <code><scope>compile</scope></code> is recommended
+for this dependency.</dd>
+<dt>OSGi / Eclipse</dt>
+<dd>When developing OSGi bundles / Eclipse plugins the version range should be specified as
+mentioned above. Unfortunately, OSGi doesn't support a concept of compile time dependencies.
+The PDE specific mechanism in file <code>build.properties</code> is problematic because
+it doesn't support specifying a version range. Thus the best approximation of the desired
+semantics is to use a <code>Require-Bundle</code> dependency.
+qualified with <code>resolution:=optional</code> in order to avoid forcing this dependency
+on the runtime:
+<pre>
+Require-Bundle: ...,
+ org.eclipse.jdt.annotation;bundle-version="[2.0.0,3.0.0)";resolution:=optional
+</pre></dd>
+</dl>
+<h3 id="compatibility_semantics">Semantics – NonNullByDefault</h3>
+<p>
+While the fundamental semantics of null annotation remains unchanged,
+the annotation <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNullByDefault.html"
+ ><code>@NonNullByDefault</code></a> has been changed slightly:
+</p>
+<ul>
+<li>This annotation can now affect more locations.</li>
+<li>The locations to be affected can be fine tuned using the
+<a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNullByDefault.html#value--"
+ ><code>value</code></a> property of the annotation
+ (see also the enum <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/DefaultLocation.html"
+ ><code>DefaultLocation</code></a>).</li>
+<li>As a consequence, the notation for canceling a default from an outer scope has been changed, too:
+<table border="1" cellspacing="0" cellpadding="5" summary="Cancelling a default">
+<tr><th>Declaration Annotations (Java 7 or below)</th><th>Type Annotation (Java 8)</th></tr>
+<tr><td><code>@NonNullByDefault(false)</code></td><td><code>@NonNullByDefault({})</code></td></tr>
+</table>
+</li>
+</ul>
+<p>
+Note, that the <code>value</code> property described here is only supported when using the annotation type
+<code>org.eclipse.jdt.annotation.NonNullByDefault</code> supplied by Eclipse.
+</p>
+<p>
+Although the Java 8 variant of
+ <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNullByDefault.html"
+ ><code>@NonNullByDefault</code></a> affects more locations, two noteworthy exceptions exist
+ (as specified in <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/DefaultLocation.html"
+ ><code>DefaultLocation</code></a>):
+<blockquote>
+ <strong>
+ Wildcards and the use of type variables are always excluded from
+ <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNullByDefault.html"
+ ><code>@NonNullByDefault</code></a>.
+ </strong>
+</blockquote>
+<p>
+By this rule, type variables and wildcards retain their intended properties as "unknowns" also in terms of nullness,
+even when they appear in the context of
+ <a href="PLUGINS_ROOT/org.eclipse.jdt.doc.isv/reference/api/org/eclipse/jdt/annotation/NonNullByDefault.html"
+ ><code>@NonNullByDefault</code></a>.
+</p>
+
+<h2 id="compiler_messages_explained">Compiler messages explained</h2>
+<p>
+In addition to
+<a href="PLUGINS_ROOT/org.eclipse.jdt.doc.user/tasks/task-using_null_annotations.htm#compiler_messages_explained"
+>compiler messages of the previous version</a> the following messages may be issued,
+if null type annotations are enabled for analysis:
+</p>
+
+<h3>General null type mismatch</h3>
+<dl>
+<dt><font color="SaddleBrown">Null type mismatch (type annotations): required 'X' but this expression has type 'Y'</font></dt>
+<dd>In an assignment context null type annotations don't match.
+ Note that the mismatch may relate to any detail of the type (type argument, array element), not necessarily to the main type.</dd>
+</dl>
+<p>
+All mismatches detected based on type annotations are prefixed with "<code>Null type mismatch (type annotations)</code>".
+</p>
+
+<h3>Various expressions</h3>
+<dl>
+<dt><font color="SaddleBrown">Potential null pointer access: array element may be null</font></dt>
+<dd>An array element is dereferenced, where the array type declares its elements as <code>@Nullable</code>.</dd>
+<dt><font color="SaddleBrown">Potential null pointer access: this expression has a '@Nullable' type</font></dt>
+<dd>Any expression at the left hand side of a dot has a type that is declared to be nullable.</dd>
+<dt><font color="SaddleBrown">Redundant null check: comparing '@NonNull X' against null</font></dt>
+<dd>An arbitrary expression known to have a @NonNull type is unnecessarily being compared against null.</dd>
+</dl>
+
+<h3>Unchecked conversions</h3>
+<dl>
+<dt><font color="SaddleBrown">Null type safety (type annotations): The expression of type 'X' needs unchecked conversion to conform to '@NonNull X'</font></dt>
+<dd>A value of an un-annotated type is being assigned to a variable of an annotated type.
+ Note that the mismatch may relate to any detail of the type (type argument, array element), not necessarily to the main type.</dd>
+<dt><font color="SaddleBrown">Null type safety: Unchecked cast from X to '@N Y'</font></dt>
+<dd>A value is casted to a null-annotated type, where the nullness is not checked at runtime by the cast.</dd>
+</dl>
+
+<h3>Problems specific to generics</h3>
+<dl>
+<dt><font color="SaddleBrown">Null constraint mismatch: The type 'X' is not a valid substitute for the type parameter 'T'</font></dt>
+<dd>Here the type parameter <code><T></code> has a constraint in one of the forms mentioned <a href="#typeParameters">above</a>.
+ The actual type argument <code>X</code>, however, doesn't conform to this constraint.</dd>
+<dt><font color="SaddleBrown">This nullness annotation conflicts with a '@N' annotation which is effective on the same type parameter</font></dt>
+<dd>A null annotation on a bound of a type parameter conflicts with another null annotation on another bound or on the type parameter itself.</dd>
+<dt><font color="SaddleBrown">Contradictory null annotations: method was inferred as 'T foo(X)', but only one of '@NonNull' and '@Nullable' can be effective at any location</font></dt>
+<dd>Type inference for a generic method invocation has produced a signature in which contradictory null annotations clash on the same element.<dd>
+<dt><font color="SaddleBrown">Null type mismatch (type annotations): 'null' is not compatible to the free type variable 'T'</font></dt>
+<dt><font color="SaddleBrown">Null type mismatch (type annotations): required 'T' but this expression has type '@Nullable T', where 'T' is a free type variable</font></dt>
+<dt><font color="SaddleBrown">Null type safety: required '@NonNull' but this expression has type 'T', a free type variable that may represent a '@Nullable' type</font></dt>
+<dt><font color="SaddleBrown">The field 'f' may not have been initialized, whereas its type 'T' is a free type variable that may represent a '@NonNull' type</font></dt>
+<dt><font color="SaddleBrown">Potential null pointer access: this expression has type 'T', a free type variable that may represent a '@Nullable' type</font></dt>
+<dd>These problems are specifically detected by <a href="#pessimistic_analysis">pessimistic analysis for free type variables</a>.</dd>
+<dt><font color="SaddleBrown">Unsafe interpretation of method return type as '@NonNull X' based on the receiver type 'Map<Y,@NonNull X>'. Type 'Map' doesn't seem to be designed with null type annotations in mind</font></dt>
+<dt><font color="SaddleBrown">Unsafe interpretation of method return type as '@NonNull X' based on substitution 'V=@NonNull X'. Declaring type 'Map<K,V>' doesn't seem to be designed with null type annotations in mind</font></dt>
+<dd>This signals a particular dilemma regarding <a href="#substitution">substitution of type variables from a legacy library</a>.
+</dl>
+
+
+<h3>Lambda expressions and method references</h3>
+For any mismatches in null annotations affecting lambda expressions or method references the corresponding
+"descriptor" is mentioned (the single abstract method being implemented by the lambda / method reference).
+This is useful for finding the origin of a null annotation that is not explicit at the current expression.
+
+
+</body>
+</html>
diff --git a/bundles/org.eclipse.jdt.doc.user/tips/images/quickfix-create-for-loop-array.txt b/bundles/org.eclipse.jdt.doc.user/tips/images/quickfix-create-for-loop-array.txt
index ab9b415..720d9b3 100644
--- a/bundles/org.eclipse.jdt.doc.user/tips/images/quickfix-create-for-loop-array.txt
+++ b/bundles/org.eclipse.jdt.doc.user/tips/images/quickfix-create-for-loop-array.txt
@@ -1,3 +1,3 @@
- void foo(int[] offsets) {
- offsets
+ void foo(int[] offsets) {
+ offsets
}
\ No newline at end of file
diff --git a/bundles/org.eclipse.platform.doc.isv/guide/st_design.htm b/bundles/org.eclipse.platform.doc.isv/guide/st_design.htm
index e2c1ad4..ca7fbc9 100644
--- a/bundles/org.eclipse.platform.doc.isv/guide/st_design.htm
+++ b/bundles/org.eclipse.platform.doc.isv/guide/st_design.htm
@@ -1,219 +1,219 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
-<HEAD>
-
-<meta name="copyright" content="Copyright (c) IBM Corporation and others 2012. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
-
-<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
-<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
-
-<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
-<TITLE>Structured Text Design</TITLE>
-
-<link rel="stylesheet" type="text/css" HREF="../book.css">
-</HEAD>
-<BODY BGCOLOR="#ffffff">
-
-<h2><a name="overview"></a>Design Overview</h2>
-
-<h3>Terms and Abbreviations</h3>
-<table border="1" callpadding = "3" cellspacing = "3" width="70%">
- <tbody><tr>
- <td>Bidi</td> <td>Bidirectional</td>
- </tr>
- <tr>
- <td>LTR</td> <td>Left to Right</td>
- </tr>
- <tr>
- <td>RTL</td> <td>Right to Left</td>
- </tr>
- <tr>
- <td>LRM</td> <td>Left-to-Right Mark</td>
- </tr>
- <tr>
- <td>RLM</td> <td>Right-to-Left Mark</td>
- </tr>
- <tr>
- <td>LRE</td> <td>Left-to-Right Embedding</td>
- </tr>
- <tr>
- <td>RLE</td> <td>Right-to-Left Embedding</td>
- </tr>
- <tr>
- <td>PDF</td> <td>Pop Directional Formatting</td>
- </tr>
-</tbody></table>
-
-<h3>General Definitions, Terminology and Conventions</h3>
-<p>Every instance of bidi text has a base text direction. Bidi text in Arabic or
-Hebrew has a RTL base direction, even if it includes numbers or Latin phrases
-which are written from left to right. Bidi text in English or Greek has a LTR
-base direction, even if it includes Arabic or Hebrew phrases which are written
-from right to left.</p>
-<p>Structured expressions also have a base text direction, which is often
-determined by the type of structured expression, but may also be affected by the
-content of the expression (whether it contains Arabic or Hebrew words).</p>
-<p>This document addresses two groups of problematic cases:</p>
-<ol>
- <li><b>Expressions with simple internal structure</b>: this category
- regroups cases in which strings are concatenated together in simple ways
- using known separators. For example: variable names, "name = value"
- specifications, file path, etc...<br>
- </li>
- <li><b>Expressions with complex internal structure</b>: this category
- regroups structured text like regular expressions, XPath expressions and
- Java code. This category differs from the previous one since the expressions
- belonging to it have a unique syntax which cannot be described by
- concatenation of string segments using separators.</li>
-</ol>
-<p>We will see that the same algorithms can handle both groups, with some
-adaptations in the details.</p>
-<p>In the <b>examples</b> appearing in this document, upper case Latin letters
-represent Arabic or Hebrew text, lower case Latin letters represent English
-text.</p>
-<p>"<b>@</b>" represents an LRM, "<b>&</b>" represents an RLM.</p>
-<p>Notations like <b>LRE+LRM</b> represent character LRE
-immediately followed by character LRM.</p>
-
-<h3>Bidirectional Control Characters</h3>
-<p>When there are problems of wrong display of bidi text, it is often possible
-to cure them by adding some bidi control characters at appropriate locations in
-the text. There are 7 bidi control characters: LRM, RLM, LRE, RLE, LRO, RLO and
-PDF. Since this design has no use for LRO and RLO (Left-to-Right and
-Right-to-Left Override, respectively), the following paragraphs will describe
-the effect of the 5 other characters.</p>
-<ul>
- <li><b>LRM</b> (Left-to-Right Mark): LRM is an invisible character which
- behaves like a letter in a Left to Right script such as Latin or Greek. It can
- be used when a segment of LTR text starts or ends with characters which are
- not intrinsically LTR and is displayed in a component with a RTL orientation.
- <br>
- Example: assume in memory the string "\\myserver\myshare(mydirectory)". We
- want it displayed identically, but within a component with RTL
- orientation it would be displayed as "(myserver\myshare(mydirectory\\". Adding
- one LRM character at the beginning of the string will cause the leading
- backslashes to be displayed on the left side, and adding one LRM character
- at the end of the string will cause the trailing parenthesis to be displayed
- on the right side.<br>
- </li>
- <li><b>RLM</b> (Right-to-Left Mark): RLM is an invisible character which
- behaves like a letter in a Right to Left script like Hebrew. It can be used
- when a segment of RTL text starts or ends with characters which are not
- intrinsically RTL and is displayed in a component with a LTR
- orientation.<br>
- Example: assume in memory the string "HELLO WORLD !". We want it displayed
- as "! DLROW OLLEH", but within a component with a LTR orientation it
- would be displayed as "DLROW OLLEH !" (exclamation mark on the right side).
- Adding one RLM character at the end of the string will cause the trailing
- exclamation mark to be displayed on the left side.<br>
- </li>
- <li><b>LRE</b> (Left-to-Right Embedding): LRE can be used to give a base
- LTR direction to a piece of text. It is most useful for mixed text which
- contains both LTR and RTL segments.<br>
- Example: assume in memory the string "i love RACHEL and LEA" which should be
- displayed as "i love LEHCAR and AEL". However, within a component with RTL
- orientation, it would be displayed as "AEL and LEHCAR i love". Adding one
- LRE character at the beginning of the string and one PDF (see below)
- character at the end of the string will cause proper display.<br>
- </li>
- <li><b>RLE</b> (Right-to-Left Embedding): RLE can be used to give a base
- RTL direction to a piece of text. It is most useful for mixed text which
- contains both LTR and RTL segments.<br>
- Example: assume in memory the string "I LOVE london AND paris" which should
- be displayed as "paris DNA london EVOL I". However, within a component with
- LTR orientation, it would be displayed as "EVOL I london DNA paris".
- Adding one RLE character at the beginning of the string and adding one PDF
- (see below) character at the end of the string will cause proper display.<br>
- </li>
- <li><b>PDF</b> (Pop Directional Formatting): PDF may be used to limit the
- effect of a preceding LRE or RLE. It may be omitted if not followed by any
- text.</li>
-</ul>
-<p>Note that pieces of text bracketed between LRE/PDF or RLE/PDF can be
-contained within larger pieces of text themselves bracketed between LRE/PDF or
-RLE/PDF. This is why the "E" of LRE and RLE means "embedding". This could happen
-if we have for instance a Hebrew sentence containing an English phrase itself
-containing an Arabic segment. In practice, such complex cases should be avoided
-if possible. The present design does not use more than one level of LRE/PDF or
-RLE/PDF, except possibly in regular expressions.</p>
-
-<h3>Bidi Classification</h3>
-<p>Characters can be classified according to their bidi type as described in the
-Unicode Standard (see
-<a href="http://www.unicode.org/reports/tr9/#Bidirectional_Character_Types">
-Bidirectional_Character_Types</a> for a full description of the bidi types). For
-our purpose, we will distinguish the following types of characters:</p>
-<ul>
- <li><b>"Strong" characters</b>: those with a bidi type of L, R or AL
- (letters in LTR or RTL scripts);</li>
- <li><b>Numbers</b>: European Numbers (type EN) or Arabic Numbers (type AN);</li>
- <li><b>Neutrals</b>: all the rest.</li>
-</ul>
-
-<h3>Text Analysis</h3>
-<p>In all the structured expressions that we are addressing, we can see characters
-with a special syntactical role that we will call "separators", and pieces of
-text between separators that we will call "tokens". The separators vary
-according to the type of structured expression. Often they are punctuation signs
-like colon (:), backslash (\) and full stop (.), or mathematical signs like Plus
-(+) or Equal (=).</p>
-<p><b>Our objective is that the relative progression of the
-tokens and separators for display should always follow the base text direction
-of the text, while each token will go LTR or RTL depending on its content and
-according to the UBA.</b></p>
-<p>For this to happen, the following must be done:</p>
-<ol>
- <li>Parse the expression to locate the separators and the tokens.<br></li>
- <li>While parsing, note the bidi classification of characters parsed.<br></li>
- <li>Depending on the bidi types of the characters before a token and in that
- token, a LRM or a RLM may have to be added. The algorithm for this is detailed below.<br></li>
- <li>If the expression has a LTR base direction and the component where
- it is displayed has a RTL orientation, add LRE+LRM at the beginning of
- the expression and LRM+PDF at its end.<br></li>
- <li>If the expression has a RTL base direction and the component where
- it is displayed has a LTR orientation, add RLE+RLM at the beginning of
- the expression and RLM+PDF at its end.<br></li>
-</ol>
-<p>The original structured expression, before addition of directional formatting
-characters, is called <em><strong>lean</strong></em> text.</p>
-<p>The processed expression, after addition of directional formatting
-characters, is called <em><strong>full</strong></em> text.</p>
-
-<h3>LRM Addition (structured text with LTR base text direction)</h3>
-<p>A LRM will be added before a token if the following conditions are satisfied:</p>
-<ul>
- <li>The last strong character before the token has a bidi type equal to R or
- AL and the first non-neutral character in the token itself has a bidi type
- equal to R, AL, EN or AN.</li>
-</ul>
-<p>Examples (strings in logical order where "@" represents where an LRM should
- be added):</p>
-<pre> HEBREW @= ARABIC
- HEBREW @= 123
-</pre>
-<p>OR</p>
-<ul>
- <li>The last non-neutral character before the token has a bidi type equal to
- AN and the first non-neutral character in the token has a bidi type equal to
- R, AL or AN.</li>
-</ul>
-<p>Examples (strings in logical order where "@" represents where an LRM should
- be added):</p>
-<pre> ARABIC NUMBER 123 @< MAX
- ARABIC NUMBER 123 @< 456
-</pre>
-
-<h3>RLM Addition (structured text with RTL base text direction)</h3>
-<p>A RLM will be added before a token if the following conditions are satisfied:</p>
-<ul>
- <li>The last strong character before the token has a bidi type equal
-to L and the first non-neutral character in the token itself has a bidi
-type
- equal to L or EN.</li>
-</ul>
-<p>Example (string in logical order where "&" represents where an RLM should
- be added):
-</p><pre> my_pet &= dog
-</pre>
-
-</BODY>
-</HTML>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
+<HEAD>
+
+<meta name="copyright" content="Copyright (c) IBM Corporation and others 2012. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
+
+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+
+<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
+<TITLE>Structured Text Design</TITLE>
+
+<link rel="stylesheet" type="text/css" HREF="../book.css">
+</HEAD>
+<BODY BGCOLOR="#ffffff">
+
+<h2><a name="overview"></a>Design Overview</h2>
+
+<h3>Terms and Abbreviations</h3>
+<table border="1" callpadding = "3" cellspacing = "3" width="70%">
+ <tbody><tr>
+ <td>Bidi</td> <td>Bidirectional</td>
+ </tr>
+ <tr>
+ <td>LTR</td> <td>Left to Right</td>
+ </tr>
+ <tr>
+ <td>RTL</td> <td>Right to Left</td>
+ </tr>
+ <tr>
+ <td>LRM</td> <td>Left-to-Right Mark</td>
+ </tr>
+ <tr>
+ <td>RLM</td> <td>Right-to-Left Mark</td>
+ </tr>
+ <tr>
+ <td>LRE</td> <td>Left-to-Right Embedding</td>
+ </tr>
+ <tr>
+ <td>RLE</td> <td>Right-to-Left Embedding</td>
+ </tr>
+ <tr>
+ <td>PDF</td> <td>Pop Directional Formatting</td>
+ </tr>
+</tbody></table>
+
+<h3>General Definitions, Terminology and Conventions</h3>
+<p>Every instance of bidi text has a base text direction. Bidi text in Arabic or
+Hebrew has a RTL base direction, even if it includes numbers or Latin phrases
+which are written from left to right. Bidi text in English or Greek has a LTR
+base direction, even if it includes Arabic or Hebrew phrases which are written
+from right to left.</p>
+<p>Structured expressions also have a base text direction, which is often
+determined by the type of structured expression, but may also be affected by the
+content of the expression (whether it contains Arabic or Hebrew words).</p>
+<p>This document addresses two groups of problematic cases:</p>
+<ol>
+ <li><b>Expressions with simple internal structure</b>: this category
+ regroups cases in which strings are concatenated together in simple ways
+ using known separators. For example: variable names, "name = value"
+ specifications, file path, etc...<br>
+ </li>
+ <li><b>Expressions with complex internal structure</b>: this category
+ regroups structured text like regular expressions, XPath expressions and
+ Java code. This category differs from the previous one since the expressions
+ belonging to it have a unique syntax which cannot be described by
+ concatenation of string segments using separators.</li>
+</ol>
+<p>We will see that the same algorithms can handle both groups, with some
+adaptations in the details.</p>
+<p>In the <b>examples</b> appearing in this document, upper case Latin letters
+represent Arabic or Hebrew text, lower case Latin letters represent English
+text.</p>
+<p>"<b>@</b>" represents an LRM, "<b>&</b>" represents an RLM.</p>
+<p>Notations like <b>LRE+LRM</b> represent character LRE
+immediately followed by character LRM.</p>
+
+<h3>Bidirectional Control Characters</h3>
+<p>When there are problems of wrong display of bidi text, it is often possible
+to cure them by adding some bidi control characters at appropriate locations in
+the text. There are 7 bidi control characters: LRM, RLM, LRE, RLE, LRO, RLO and
+PDF. Since this design has no use for LRO and RLO (Left-to-Right and
+Right-to-Left Override, respectively), the following paragraphs will describe
+the effect of the 5 other characters.</p>
+<ul>
+ <li><b>LRM</b> (Left-to-Right Mark): LRM is an invisible character which
+ behaves like a letter in a Left to Right script such as Latin or Greek. It can
+ be used when a segment of LTR text starts or ends with characters which are
+ not intrinsically LTR and is displayed in a component with a RTL orientation.
+ <br>
+ Example: assume in memory the string "\\myserver\myshare(mydirectory)". We
+ want it displayed identically, but within a component with RTL
+ orientation it would be displayed as "(myserver\myshare(mydirectory\\". Adding
+ one LRM character at the beginning of the string will cause the leading
+ backslashes to be displayed on the left side, and adding one LRM character
+ at the end of the string will cause the trailing parenthesis to be displayed
+ on the right side.<br>
+ </li>
+ <li><b>RLM</b> (Right-to-Left Mark): RLM is an invisible character which
+ behaves like a letter in a Right to Left script like Hebrew. It can be used
+ when a segment of RTL text starts or ends with characters which are not
+ intrinsically RTL and is displayed in a component with a LTR
+ orientation.<br>
+ Example: assume in memory the string "HELLO WORLD !". We want it displayed
+ as "! DLROW OLLEH", but within a component with a LTR orientation it
+ would be displayed as "DLROW OLLEH !" (exclamation mark on the right side).
+ Adding one RLM character at the end of the string will cause the trailing
+ exclamation mark to be displayed on the left side.<br>
+ </li>
+ <li><b>LRE</b> (Left-to-Right Embedding): LRE can be used to give a base
+ LTR direction to a piece of text. It is most useful for mixed text which
+ contains both LTR and RTL segments.<br>
+ Example: assume in memory the string "i love RACHEL and LEA" which should be
+ displayed as "i love LEHCAR and AEL". However, within a component with RTL
+ orientation, it would be displayed as "AEL and LEHCAR i love". Adding one
+ LRE character at the beginning of the string and one PDF (see below)
+ character at the end of the string will cause proper display.<br>
+ </li>
+ <li><b>RLE</b> (Right-to-Left Embedding): RLE can be used to give a base
+ RTL direction to a piece of text. It is most useful for mixed text which
+ contains both LTR and RTL segments.<br>
+ Example: assume in memory the string "I LOVE london AND paris" which should
+ be displayed as "paris DNA london EVOL I". However, within a component with
+ LTR orientation, it would be displayed as "EVOL I london DNA paris".
+ Adding one RLE character at the beginning of the string and adding one PDF
+ (see below) character at the end of the string will cause proper display.<br>
+ </li>
+ <li><b>PDF</b> (Pop Directional Formatting): PDF may be used to limit the
+ effect of a preceding LRE or RLE. It may be omitted if not followed by any
+ text.</li>
+</ul>
+<p>Note that pieces of text bracketed between LRE/PDF or RLE/PDF can be
+contained within larger pieces of text themselves bracketed between LRE/PDF or
+RLE/PDF. This is why the "E" of LRE and RLE means "embedding". This could happen
+if we have for instance a Hebrew sentence containing an English phrase itself
+containing an Arabic segment. In practice, such complex cases should be avoided
+if possible. The present design does not use more than one level of LRE/PDF or
+RLE/PDF, except possibly in regular expressions.</p>
+
+<h3>Bidi Classification</h3>
+<p>Characters can be classified according to their bidi type as described in the
+Unicode Standard (see
+<a href="http://www.unicode.org/reports/tr9/#Bidirectional_Character_Types">
+Bidirectional_Character_Types</a> for a full description of the bidi types). For
+our purpose, we will distinguish the following types of characters:</p>
+<ul>
+ <li><b>"Strong" characters</b>: those with a bidi type of L, R or AL
+ (letters in LTR or RTL scripts);</li>
+ <li><b>Numbers</b>: European Numbers (type EN) or Arabic Numbers (type AN);</li>
+ <li><b>Neutrals</b>: all the rest.</li>
+</ul>
+
+<h3>Text Analysis</h3>
+<p>In all the structured expressions that we are addressing, we can see characters
+with a special syntactical role that we will call "separators", and pieces of
+text between separators that we will call "tokens". The separators vary
+according to the type of structured expression. Often they are punctuation signs
+like colon (:), backslash (\) and full stop (.), or mathematical signs like Plus
+(+) or Equal (=).</p>
+<p><b>Our objective is that the relative progression of the
+tokens and separators for display should always follow the base text direction
+of the text, while each token will go LTR or RTL depending on its content and
+according to the UBA.</b></p>
+<p>For this to happen, the following must be done:</p>
+<ol>
+ <li>Parse the expression to locate the separators and the tokens.<br></li>
+ <li>While parsing, note the bidi classification of characters parsed.<br></li>
+ <li>Depending on the bidi types of the characters before a token and in that
+ token, a LRM or a RLM may have to be added. The algorithm for this is detailed below.<br></li>
+ <li>If the expression has a LTR base direction and the component where
+ it is displayed has a RTL orientation, add LRE+LRM at the beginning of
+ the expression and LRM+PDF at its end.<br></li>
+ <li>If the expression has a RTL base direction and the component where
+ it is displayed has a LTR orientation, add RLE+RLM at the beginning of
+ the expression and RLM+PDF at its end.<br></li>
+</ol>
+<p>The original structured expression, before addition of directional formatting
+characters, is called <em><strong>lean</strong></em> text.</p>
+<p>The processed expression, after addition of directional formatting
+characters, is called <em><strong>full</strong></em> text.</p>
+
+<h3>LRM Addition (structured text with LTR base text direction)</h3>
+<p>A LRM will be added before a token if the following conditions are satisfied:</p>
+<ul>
+ <li>The last strong character before the token has a bidi type equal to R or
+ AL and the first non-neutral character in the token itself has a bidi type
+ equal to R, AL, EN or AN.</li>
+</ul>
+<p>Examples (strings in logical order where "@" represents where an LRM should
+ be added):</p>
+<pre> HEBREW @= ARABIC
+ HEBREW @= 123
+</pre>
+<p>OR</p>
+<ul>
+ <li>The last non-neutral character before the token has a bidi type equal to
+ AN and the first non-neutral character in the token has a bidi type equal to
+ R, AL or AN.</li>
+</ul>
+<p>Examples (strings in logical order where "@" represents where an LRM should
+ be added):</p>
+<pre> ARABIC NUMBER 123 @< MAX
+ ARABIC NUMBER 123 @< 456
+</pre>
+
+<h3>RLM Addition (structured text with RTL base text direction)</h3>
+<p>A RLM will be added before a token if the following conditions are satisfied:</p>
+<ul>
+ <li>The last strong character before the token has a bidi type equal
+to L and the first non-neutral character in the token itself has a bidi
+type
+ equal to L or EN.</li>
+</ul>
+<p>Example (string in logical order where "&" represents where an RLM should
+ be added):
+</p><pre> my_pet &= dog
+</pre>
+
+</BODY>
+</HTML>
diff --git a/bundles/org.eclipse.platform.doc.isv/guide/st_structured_text.htm b/bundles/org.eclipse.platform.doc.isv/guide/st_structured_text.htm
index a6f38ed..d97281d 100644
--- a/bundles/org.eclipse.platform.doc.isv/guide/st_structured_text.htm
+++ b/bundles/org.eclipse.platform.doc.isv/guide/st_structured_text.htm
@@ -1,60 +1,60 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
-<HEAD>
-
-<meta name="copyright" content="Copyright (c) IBM Corporation and others 2012. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
-
-<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
-<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
-
-<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
-<TITLE>Structured Text Overview</TITLE>
-
-<link rel="stylesheet" type="text/css" HREF="../book.css">
-</HEAD>
-<BODY BGCOLOR="#ffffff">
-
-<H2>Structured Text Overview</H2>
-
-<p>Languages like Arabic and Hebrew are generally written from right to left,
-but included numbers and phrases in English must be written from left to right.
-This is the origin of the term "bidirectional" which qualifies these languages.</p>
-<p>In most computer environments, the text is stored in <em>logical</em> order
-(the order the text is read) but is reordered into <em>visual</em> order for
-presentation. For plain text, the Unicode Bidirectional Algorithm
-(<a href="http://www.unicode.org/reports/tr9/">UBA</a>)
-generally specifies satisfactorily how to reorder bidirectional text for
-display. This algorithm, or close to it, is implemented in the presentation
-systems of a number of platforms, giving them a good handle on bidirectional
-support.</p>
-<p>However, all bidirectional text is not necessarily plain text. There are also
-instances of text structured to follow a given syntax, which should be reflected
-in the display order. The general algorithm, which has no awareness of these
-special cases, often gives incorrect results when displaying such structured
-text.</p>
-<p>This document describes various examples of this issue, and proposes a
-methodology to solve the related problems. The types of structured text treated
-in this document are all excerpted from actual products, including Eclipse.</p>
-<p>For a general introduction to bidirectional concepts, the reader is kindly
-referred to the following technical article: "Bidirectional script support: a
-primer" available at
-<a href="http://www-128.ibm.com/developerworks/websphere/library/techarticles/bidi/bidigen.html">
-http://www-128.ibm.com/developerworks/websphere/library/techarticles/bidi/bidigen.html</a>.</p>
-
-<h3>Working with Structured Text</h3>
-
-<p>Eclipse provides support for correct presentation of structured text. The base
-functionality can be found in the package <b>"org.eclipse.equinox.bidi"</b>.
-The methods <code>process()</code> and <code>deprocess()</code> and their variants
-in class STextProcessor will be a good starting point.</p>
-
-<p>Consumers who would like to adjust Bidi environment settings, process bidi
-text in portions, or directly manage directional formatting will find lower level
-functionality available in the <b>"org.eclipse.equinox.bidi.advanced"</b> package.</p>
-
-<p>Developers wishing to create handlers for types of structured text not
-currently supported by Eclipse "out of the box" will create extensions for class STextTypeHandler
-in package <b>"org.eclipse.equinox.bidi.advanced"</b>. Such new type handlers
-should register with the <b>"org.eclipse.equinox.bidi.bidiTypes"</b> extension point.</p>
-
-</BODY>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
+<HEAD>
+
+<meta name="copyright" content="Copyright (c) IBM Corporation and others 2012. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
+
+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+
+<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
+<TITLE>Structured Text Overview</TITLE>
+
+<link rel="stylesheet" type="text/css" HREF="../book.css">
+</HEAD>
+<BODY BGCOLOR="#ffffff">
+
+<H2>Structured Text Overview</H2>
+
+<p>Languages like Arabic and Hebrew are generally written from right to left,
+but included numbers and phrases in English must be written from left to right.
+This is the origin of the term "bidirectional" which qualifies these languages.</p>
+<p>In most computer environments, the text is stored in <em>logical</em> order
+(the order the text is read) but is reordered into <em>visual</em> order for
+presentation. For plain text, the Unicode Bidirectional Algorithm
+(<a href="http://www.unicode.org/reports/tr9/">UBA</a>)
+generally specifies satisfactorily how to reorder bidirectional text for
+display. This algorithm, or close to it, is implemented in the presentation
+systems of a number of platforms, giving them a good handle on bidirectional
+support.</p>
+<p>However, all bidirectional text is not necessarily plain text. There are also
+instances of text structured to follow a given syntax, which should be reflected
+in the display order. The general algorithm, which has no awareness of these
+special cases, often gives incorrect results when displaying such structured
+text.</p>
+<p>This document describes various examples of this issue, and proposes a
+methodology to solve the related problems. The types of structured text treated
+in this document are all excerpted from actual products, including Eclipse.</p>
+<p>For a general introduction to bidirectional concepts, the reader is kindly
+referred to the following technical article: "Bidirectional script support: a
+primer" available at
+<a href="http://www-128.ibm.com/developerworks/websphere/library/techarticles/bidi/bidigen.html">
+http://www-128.ibm.com/developerworks/websphere/library/techarticles/bidi/bidigen.html</a>.</p>
+
+<h3>Working with Structured Text</h3>
+
+<p>Eclipse provides support for correct presentation of structured text. The base
+functionality can be found in the package <b>"org.eclipse.equinox.bidi"</b>.
+The methods <code>process()</code> and <code>deprocess()</code> and their variants
+in class STextProcessor will be a good starting point.</p>
+
+<p>Consumers who would like to adjust Bidi environment settings, process bidi
+text in portions, or directly manage directional formatting will find lower level
+functionality available in the <b>"org.eclipse.equinox.bidi.advanced"</b> package.</p>
+
+<p>Developers wishing to create handlers for types of structured text not
+currently supported by Eclipse "out of the box" will create extensions for class STextTypeHandler
+in package <b>"org.eclipse.equinox.bidi.advanced"</b>. Such new type handlers
+should register with the <b>"org.eclipse.equinox.bidi.bidiTypes"</b> extension point.</p>
+
+</BODY>
</HTML>
\ No newline at end of file
diff --git a/bundles/org.eclipse.platform.doc.isv/guide/st_text_types.htm b/bundles/org.eclipse.platform.doc.isv/guide/st_text_types.htm
index 54f97b5..203bdee 100644
--- a/bundles/org.eclipse.platform.doc.isv/guide/st_text_types.htm
+++ b/bundles/org.eclipse.platform.doc.isv/guide/st_text_types.htm
@@ -1,478 +1,478 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
-<HEAD>
-
-<meta name="copyright" content="Copyright (c) IBM Corporation and others 2012. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
-
-<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
-<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
-
-<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
-<TITLE>Supported Text Types</TITLE>
-
-<link rel="stylesheet" type="text/css" HREF="../book.css">
-</HEAD>
-<BODY BGCOLOR="#ffffff">
-
-<h2>Supported Text Types</h2>
-<p>Out-of-the-box we include support for the following text types:</p>
-<ul>
- <li><a href="#comma">Comma-delimited List</a></li>
-<!-- missing: <li><a href="#email">e-mail address</a></li> -->
- <li><a href="#file">Full Path - Relative Path - File Name</a></li>
- <li><a href="#java">Java Code</a></li>
- <li><a href="#regex">Regular Expression</a></li>
-<!-- missing: <li><a href="#sql">SQL statement</a></li> -->
- <li><a href="#underscore">Compound Name with Underscores</a></li>
- <li><a href="#url">URL, URI, IRI</a></li>
- <li><a href="#xpath">XPath</a></li>
-
-<!-- dropped:
- <li><a href="#userid">System, Userid Specification</a></li>
- <li><a href="#math">Mathematical Formula</a></li>
- <li><a href="#property">Property File</a></li>
- <li><a href="#message">Message with Placeholders</a></li>
--->
-</ul>
-<p>Developers can add custom text types by contributing to the <code>org.eclipse.equinox.bidi.bidiTypes</code>
-extension point.</p>
-<p>Unless specified otherwise, we assume that the relative progression of the tokens and separators for display
-should always be from left to right, while the text of each token will go LTR or
-RTL depending on its content and according to the Unicode Bidirectional Algorithm.</p>
-<p>(In the examples, "<b>@</b>" represents an LRM, "<b>&</b>" represents an RLM.)</p>
-
-<h3><a name="comma"></a>Comma-delimited List (<code>comma</code>)</h3>
-<h4>Pattern</h4>
-<p><span style="color:blue">[first list item]</span> <span style="color:red"><b>
-,</b></span> <span style="color:blue">[second list item]</span>
-<span style="color:red"><b>,</b></span> <span style="color:blue">. . .</span>
-<span style="color:red"><b>,</b></span> <span style="color:blue">[last list
-item]</span> </p>
-<h4>Detailed Design</h4>
-<p>The general algorithm applies, with the
-following adaptations:</p>
-<ul>
- <li>There is only one separator, the comma(,). </li>
- <li>This design can easily be adapted to accomodate a different separator,
- like a semicolon (;) or a tab character, etc... </li>
-</ul>
-<b>Example:</b>
-<pre> Logical order (without LRM): ABC,DE,FGH
- Display (without LRM): HGF,ED,CBA
- Logical order (with LRM): ABC@,DE@,FGH
- Display (without LRM): CBA,ED,HGF
-</pre>
-
-<h3><a name="file"></a>Name or Path of File or Directory </h3>
-<h4>Patterns</h4>
-<p><u>Windows full path:</u> <span style="color:blue">[drive letter]</span><span style="color:red"><b>:\</b></span>
-<span style="color:blue">[sub-path]</span> <span style="color:red"><b>\</b></span>
-<span style="color:blue">. . .</span> <span style="color:red"><b>\</b></span>
-<span style="color:blue">[sub-path]</span></p>
-<p><u>Windows relative path:</u> <span style="color:blue">[sub-path]</span>
-<span style="color:red"><b>\</b></span> <span style="color:blue">. . .</span>
-<span style="color:red"><b>\</b></span> <span style="color:blue">[sub-path]</span></p>
-<p><u>Windows full file path:</u> <span style="color:blue">[drive letter]</span><span style="color:red"><b>:\</b></span>
-<span style="color:blue">[sub-path]</span> <span style="color:red"><b>\</b></span>
-<span style="color:blue">. . .</span> <span style="color:red"><b>\</b></span>
-<span style="color:blue">[sub-path]</span> <span style="color:red"><b>\</b></span>
-<span style="color:blue">[file name]</span> <span style="color:red"><b>.</b></span>
-<span style="color:blue">[extension]</span></p>
-<p><u>Windows relative file path:</u> <span style="color:blue">[sub-path]</span>
-<span style="color:red"><b>\</b></span> <span style="color:blue">. . .</span>
-<span style="color:red"><b>\</b></span> <span style="color:blue">[sub-path]</span>
-<span style="color:red"><b>\</b></span> <span style="color:blue">[file name]</span>
-<span style="color:red"><b>.</b></span> <span style="color:blue">[extension]</span></p>
-<p><u>Linux full path:</u> <span style="color:red"><b>/</b></span>
-<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
-<span style="color:blue">. . .</span> <span style="color:red"><b>/</b></span>
-<span style="color:blue">[sub-path]</span></p>
-<p><u>Linux relative path:</u> <span style="color:blue">[sub-path]</span>
-<span style="color:red"><b>/</b></span> <span style="color:blue">. . .</span>
-<span style="color:red"><b>/</b></span> <span style="color:blue">[sub-path]</span></p>
-<p><u>Linux full file path:</u> <span style="color:red"><b>/</b></span>
-<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
-<span style="color:blue">. . .</span> <span style="color:red"><b>/</b></span>
-<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
-<span style="color:blue">[file name]</span> <span style="color:red"><b>.</b></span>
-<span style="color:blue">[extension]</span></p>
-<p><u>Linux relative file path:</u> <span style="color:blue">[sub-path]</span>
-<span style="color:red"><b>/</b></span> <span style="color:blue">. . .</span>
-<span style="color:red"><b>/</b></span> <span style="color:blue">[sub-path]</span>
-<span style="color:red"><b>/</b></span> <span style="color:blue">[file name]</span>
-<span style="color:red"><b>.</b></span> <span style="color:blue">[extension]</span></p>
-<h4>Detailed Design</h4>
-<p>The general algorithm applies, with the
-following adaptation:</p>
-<ul>
- <li>The separators are colon (:), backslash (\) and full stop (.) for
- Windows, slash (/) and full stop (.) for Linux. </li>
-</ul>
-<b>Example:</b>
-<pre> Logical order (without LRM): c:\DIR1\DIR2\MYFILE.ext
- Display (without LRM): c:\ELIFYM\2RID\1RID.ext
- Logical order (with LRM): c:\DIR1@\DIR2@\MYFILE.ext
- Display (without LRM): c:\1RID\2RID\ELIFYM.ext
-</pre>
-
-<h3><a name="java"></a>Java Code</h3>
-<h4>Requirement</h4>
-<p>We can classify elements of a Java program as: </p>
-<ul>
- <li>white space </li>
- <li>operators </li>
- <li>String literals: they start with a double quote and end with a double
- quote which is not escaped (not preceded by a backslash). </li>
- <li>comments: they start with /* and end with */ or start with // and end at
- the end of the line. </li>
- <li>tokens: anything delimited by the previous items. </li>
-</ul>
-<p>The requirement is to make the relative order of elements left-to-right,
-while each element by itself will be presented according to the Unicode Bidirectional Algorithm. </p>
-<h4>Detailed Design</h4>
-<p>The general algorithm applies, with the
-following adaptations:</p>
-<ul>
- <li>Each String literal or comment is considered as one token. </li>
- <li>The separators are all the characters used as operators and separators
- in the Java language: plus (+), minus (-), asterisk (*), slash (/), percent
- (%), less-than (<), greater-than (>), ampersand (&), vertical bar (|),
- circumflex (^), tilde (~), left and right parentheses ( ( ) ), left and
- right square brackets ([ ]), left and right curly brackets ( { } ), comma
- (,), full stop (.), semicolon (;), exclamation mark (!), question mark (?),
- colon (:), spaces which are not part of a String literal or a comment. </li>
- <li>If a String literal or a comment includes LRE or RLE characters but do
- not include the proper number of matching PDF characters, missing PDF
- characters must be added at the end of the literal or comment.</li>
-</ul>
-<b>Example:</b>
-<pre> Logical order (without LRM): A = /*B+C*/ D;
- Display (without LRM): D /*C+B*/ = A;
- Logical order (with LRM): A@ = /*B+C@*/ D;
- Display (without LRM): A = /*C+B*/ D;
-</pre>
-
-<h3><a name="regex"></a>Regular Expression</h3>
-<h4>Requirement</h4>
-<p>Preserve the relative order of the regular expression components identical to
-the order in which they appear when exclusively Latin characters are used.</p>
-<h4>Detailed Design</h4>
-<p>The general algorithm applies, with the
-following adaptations:</p>
-<ul>
- <li>Regular expressions consist of operators, pattern characters, and
- " in most implementations of extended syntax " named identifiers.</li>
- <li>Since the syntax of regular expression is not standardized, the
- list of operators should be adapted to the specific implementation at hand.
- </li>
- <li>Common operators include: question mark (?), circumflex (^), dollar ($), plus
- (+), minus (-), asterisk (*), vertical bar (|), tilde (~), left and right
- parentheses ( ( ) ), left and right square brackets ([ ]), left and right
- curly brackets ( { } ), commercial at (@), number sign (#), ampersand (&),
- backslash (\).</li>
- <li>The separators will be the characters used as operators for regular
- expressions.</li>
- <li>Characters which are not operators are pattern characters.
- If an operator is immediately preceded by a backslash, both the
- backslash and the operator must be handled as pattern characters.</li>
- <li>Each pattern character is a separate token, so pattern characters
- will always be ordered according to the base text direction of the
- expression.</li>
- <li>Identifiers appear in certain syntactic constructs, and are treated as
- tokens. For example, the strings "digit" and "number" in the expression
- "total: (?<number>[:digit:]+)\s" are identifiers, whereas "total" is just
- a sequence of 5 pattern characters.</li>
- <li>The following constructs must be recognized as delimiting tokens
- (note: this list should be adapted to the specific syntax of regular
- expressions in a given environment):<br>
- (?<name><br>
- (?'name'<br>
- (?(<name>)<br>
- (?('name')<br>
- (?(name)<br>
- (?&name)<br>
- (?P<name><br>
- \k<name><br>
- \k'name'<br>
- \k{name}<br>
- (?P=name)<br>
- \g{name}<br>
- \g<name><br>
- \g'name'<br>
- (?(R&name)<br>
- [:class:]<br>
- </li>
- <li>Comments of the form (?# . . . ) must be handled as individual tokens.</li>
- <li>Quoted sequences of the form \Q . . . \E must be handled as individual tokens.</li>
- <li>Numbers used as quantifiers (numbers of occurrences) or as group references
- must be handled as individual tokens.</li>
- <li>If the first strong directional character in a regular expression is an
- Arabic letter, the base direction of the expression must be RTL.</li>
- <li>If the first strong directional character in a regular expression is a
- Hebrew letter or a LTR letter, the base direction of the expression must be
- LTR.</li>
- <li>If the regular expression contains no strong directional character, its
- base direction must be LTR for Hebrew users. For Arabic users, its base
- direction should follow the user interface direction (RTL if mirrored, LTR otherwise).</li>
-</ul>
-<b>Example (Hebrew):</b>
-<pre> Logical order (without LRM): ABC(?'DEF'GHI
- Display (without LRM): IHG'FED'?(CBA
- Logical order (with LRM): A@B@C@(?'DEF'@G@H@I
- Display (without LRM): ABC(?'FED'GHI
-</pre>
-<b>Example (Arabic):</b>
-<pre> Logical order (without LRM): ABC(?'DEF'GHI
- Display (without LRM): IHG'FED'?(CBA
- Logical order (with LRM): ABC(?'DEF'GHI
- Display (without LRM): IHG'FED'?(CBA
-</pre>
-
-<h3><a name="underscore"></a>Compound Name with Underscores</h3>
-<h4>Pattern</h4>
-<p><span style="color:blue">[first part]</span> <span style="color:red"><b>_</b></span>
-<span style="color:blue">[second part]</span> <span style="color:red"><b>_</b></span>
-<span style="color:blue">[third part]</span> </p>
-<p>Note: name parts must not include underscores.</p>
-<h4>Detailed Design</h4>
-<p>The general algorithm applies, with the
-following adaptation:</p>
-<ul>
- <li>There is only one separator, the underscore (_). </li>
-</ul>
-<b>Example:</b>
-<pre> Logical order (without LRM): MYPACKAGE_MYPROGRAM
- Display (without LRM): MARGORPYM_EGAKCAPYM
- Logical order (with LRM): MYPACKAGE@_MYPROGRAM
- Display (without LRM): EGAKCAPYM_MARGORPYM
-</pre>
-
-<h3><a name="url"></a>URL, URI, IRI</h3>
-<h4>Patterns</h4>
-<p><span style="color:red"><b>http://</b></span> <span style="color:blue">
-[domain label]</span> <span style="color:red"><b>.</b></span>
-<span style="color:blue">. . .</span> <span style="color:red"><b>.</b></span>
-<span style="color:blue">[domain label]</span></p>
-<p><span style="color:red"><b>http://</b></span> <span style="color:blue">
-[domain label]</span> <span style="color:red"><b>.</b></span>
-<span style="color:blue">. . .</span> <span style="color:red"><b>.</b></span>
-<span style="color:blue">[domain label]</span> <span style="color:red"><b>/</b></span>
-<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
-<span style="color:blue">. . .</span> <span style="color:red"><b>/</b></span>
-<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
-<span style="color:blue">[file name]</span> <span style="color:red"><b>.</b></span>
-<span style="color:blue">[extension]</span></p>
-<p><span style="color:red"><b>http://</b></span> <span style="color:blue">
-[domain label]</span> <span style="color:red"><b>.</b></span>
-<span style="color:blue">. . .</span> <span style="color:red"><b>.</b></span>
-<span style="color:blue">[domain label]</span> <span style="color:red"><b>/</b></span>
-<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
-<span style="color:blue">. . .</span> <span style="color:red"><b>/</b></span>
-<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
-<span style="color:blue">[file name]</span> <span style="color:red"><b>.</b></span>
-<span style="color:blue">[extension]</span> <span style="color:red"><b>#</b></span>
-<span style="color:blue">[local reference]</span> </p>
-<p><span style="color:red"><b>http://</b></span> <span style="color:blue">
-[domain label]</span> <span style="color:red"><b>.</b></span>
-<span style="color:blue">. . .</span> <span style="color:red"><b>.</b></span>
-<span style="color:blue">[domain label]</span> <span style="color:red"><b>/</b></span>
-<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
-<span style="color:blue">. . .</span> <span style="color:red"><b>/</b></span>
-<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
-<span style="color:blue">[file name]</span> <span style="color:red"><b>.</b></span>
-<span style="color:blue">[extension]</span> <span style="color:red"><b>?</b></span>
-<span style="color:blue">[key1]</span> <span style="color:red"><b>=</b></span>
-<span style="color:blue">[value1]</span> <span style="color:red"><b>&</b></span>
-<span style="color:blue">[key2]</span> <span style="color:red"><b>=</b></span>
-<span style="color:blue">[value2]</span></p>
-<h4>Detailed Design</h4>
-<p>The general algorithm applies, with the
-following adaptations:</p>
-<ul>
- <li>The detailed syntax of URLs, URIs, IRIs is described in
- <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a> and
- <a href="http://www.ietf.org/rfc/rfc3987.txt">RFC 3987</a>. A rigorous
- analysis to identify tokens and separators is not simple. </li>
- <li>For most practical cases, it is sufficient to consider the following
- separators: colon (:), question mark (?), number sign (#), slash (/),
- commercial at (@), full stop (.), left bracket ([), right bracket (]). </li>
-</ul>
-<b>Example:</b>
-<pre> Logical order (without LRM): www.DOC.MYDOMAIN.com\HEB\LESSON1.html
- Display (without LRM): www.NIAMODYM.COD.com\1NOSSEL\BEH.html
- Logical order (with LRM): www.DOC@.MYDOMAIN.com\HEB@\LESSON1.html
- Display (without LRM): www.COD.NIAMODYM.com\BEH\1NOSSEL.html
-</pre>
-
-<h3><a name="xpath"></a>XPath</h3>
-<h4>Patterns</h4>
-<p><span style="color:red"><b>/</b></span> <span style="color:blue">book</span>
-<span style="color:red"><b>/</b></span> <span style="color:blue">chapter</span>
-<span style="color:red"><b>/</b></span> <span style="color:blue">paragraph</span></p>
-<p><span style="color:red"><b>/</b></span> <span style="color:blue">year</span>
-<span style="color:red"><b>/</b></span> <span style="color:blue">month</span>
-<span style="color:red"><b>[@</b></span><span style="color:blue">name</span>
-<span style="color:red"><b>=</b></span> <span style="color:red"><b>"</b></span><span style="color:blue">April</span><span style="color:red"><b>"]</b></span>
-</p>
-<h4>Detailed Design</h4>
-<p>The general algorithm applies, with the
-following adaptations:</p>
-<ul>
- <li><b><u>Strings</u></b>
- <ul>
- <li>Strings are started by a <i>quotation mark</i> which can be a
- double-quote (") or an apostrophe ('), and are closed by the same
- character. </li>
- <li>Double-quotes may appear within a string limited by apostrophes and
- vice versa, and must be handled as characters internal to the string.
- </li>
- <li>A string started on one line is not necessarily closed on the same
- line.</li>
- </ul>
- </li>
- <li><b><u>Whitespace</u></b> (e.g. blanks and tab characters) appearing
- outside of strings constitutes a delimiter for tokens.
- </li>
- <li>Each occurrence of a string must be handled as one token.
- </li>
- <li>After isolating strings, the following characters are separators: white
- space, slash (/), square brackets ( [ and ] ), less-than (<), greater-than
- (>), equal sign (=), exclamation mark (!), colon (:), at sign (@), period
- (.), vertical bar (|), parentheses ( ( and ) ), plus (+), minus (-),
- asterisk (*).
- </li>
- <li>Some operators are words like "and", "or", "div", "mod". For our
- purpose, they can be handled as tokens.
- </li>
- <li>Some operators are represented by a pair of symbols like "not equal"
- (!=), "descendant-or-self" (//), "parent" (..). For our purpose, they can be
- handled as 2 successive operators represented by one symbol each. </li>
-</ul>
-<b>Example:</b>
-<pre> Logical order (without LRM): DEF!GHI 'A!B'=JK
- Display (without LRM): KJ='B!A' IHG!FED
- Logical order (with LRM): DEF@!GHI@ 'A!B'@=JK
- Display (without LRM): FED!IHG 'B!A'=KJ
-</pre>
-
-<!-- dropped:
-<h3><a name="property"></a>Property File</h3>
-<h4>Pattern</h4>
-<p><span style="color:blue">[variable name]</span> <span style="color:red"><b>=</b></span>
-<span style="color:blue">[value]</span> </p>
-<p>Note: variable names must not include equal signs.</p>
-<h4>Detailed Design</h4>
-<p>The general algorithm applies, with the
-following adaptations:</p>
-<ul>
- <li>There is only one separator, the equal sign (=).</li>
- <li>It is enough to locate the first occurrence of the separator. Everything
- before can be considered as the first token, everything after can be
- considered the second (and last) token.</li>
-</ul>
-<b>Example:</b>
-<pre> Logical order (without LRM): PRIORITY=5
- Display (without LRM): 5=YTIROIRP
- Logical order (with LRM): PRIORITY@=5
- Display (without LRM): YTIROIRP=5
-</pre>
-
-<h3><a name="userid"></a>System, Userid Specification</h3>
-<h4>Pattern</h4>
-<p><span style="color:blue">[system ID]</span> <span style="color:red"><b>(</b></span>
-<span style="color:blue">[user ID]</span> <span style="color:red"><b>)</b></span>
-</p>
-<p>Note: the system ID must not include parentheses.</p>
-<h4>Detailed Design</h4>
-<p>The general algorithm applies, with the
-following adaptations:</p>
-<ul>
- <li>It is enough to consider one separator, the left parenthesis ( ( ). </li>
- <li>It is enough to locate the first occurrence of the separator. Everything
- before can be considered as the first token, everything after can be
- considered the second (and last) token. </li>
-</ul>
-<b>Example:</b>
-<pre> Logical order (without LRM): MY_HOST(MY_USERID)
- Display (without LRM): DIRESU_YM)TSOH_YM)
- Logical order (with LRM): MY_HOST@(MY_USERID)
- Display (without LRM): TSOH_YM(DIRESU_YM)
-</pre>
-
-<h3><a name="math"></a>Mathematical Formula</h3>
-<h4>Requirement</h4>
-<p>Preserve the relative order of the formula components according to the
-base text direction of the formula.</p>
-<h4>Detailed Design</h4>
-<p>The general algorithm applies, with the
-following adaptations:</p>
-<ul>
- <li>The separators are the usual arithmetic operators. </li>
- <li>Tokens will be ordered according to the base text direction of the
- formula.</li>
- <li>If the first strong directional character in the formula is a Hebrew or
- LTR letter, the base text direction of the formula is LTR.</li>
- <li>If the first strong directional character in the formula is an
- Arabic letter, the base direction of the formula must be RTL.</li>
- <li>If there is no strong directional character in the formula but there are
- Arabic-Indic digits, the base direction of the formula must be
- RTL, otherwise it must be LTR.</li>
-</ul>
-<b>Example (Hebrew):</b>
-<pre> Logical order (without LRM): PROFIT = REVENUE - COST
- Display (without LRM): TSOC - EUNEVER = TIFORP
- Logical order (with LRM): PROFIT @= REVENUE @- COST
- Display (without LRM): TIFORP = EUNEVER - TSOC
-</pre>
-<b>Example (Arabic, ampersand represents RLM):</b>
-<pre> Logical order (without LRM): DIVIDEND = SHARE x 0.10
- Display (without LRM): x 0.10 ERAHS = DNEDIVID
- Logical order (with LRM): DIVIDEND = SHARE x& 0.10
- Display (without LRM): 0.10 x ERAHS = DNEDIVID
-</pre>
-
-<h3><a name="message"></a>Message with Placeholders</h3>
-<p>Products often use template messages where placeholders are replaced by
-custom data at run time.</p>
-<h4>Requirement</h4>
-<p>The display considerations must ensure correct presentation of both the
-template text and the custom data replacing the placeholders, taking in account
-that these data might have an internal structure, which should be preserved.</p>
-<h4>Detailed Design</h4>
-<ol>
- <li>The message template will be considered as having a LTR base direction
- if it is not translated, a RTL base direction if it is translated to Arabic
- or Hebrew.</li>
- <li>Let us call "insertion unit" a piece of custom data which is to replace
- a placeholder. Insertion units with an internal structure also have a
- defined base direction, generally LTR. For insertion units without internal
- structure, their base direction will be defined as RTL if they contain at
- least one Arabic or Hebrew letter, LTR otherwise.</li>
- <li> Each insertion unit with an internal structure must be processed
- according to its specific structure.</li>
- <li>If the base direction of an insertion unit is the same as that of the
- template, there is nothing more to do for it.</li>
- <li>If the base direction of the template is LTR and the
- base direction of an insertion unit is RTL, the insertion unit should have
- RLE+RLM added at its beginning and RLM+PDF added at its end.</li>
- <li>If the base direction of the template is RTL and the
- base direction of an insertion unit is LTR, the insertion unit should have
- LRE+LRM added at its beginning and LRM+PDF added at its end.</li>
- <li>If the component in which the formatted message is
- displayed has an orientation different from the template direction, the formatted
- message must have LRE+LRM added to its beginning and LRM+PDF added to its
- end if its base direction is LTR, RLE+RLM added to its beginning and
- RLM+PDF added to its end if its base direction is RTL.</li>
-</ol>
-<b>Example</b> (">" represents LRE, "^" represents PDF, "@" represents LRM)<b>:</b>
-<pre> Logical order (template without LRM): err012: FILE "%1" NOT FOUND!
- Logical order (%1 without LRM): c:\DIR1\MYFILE.ext
- Display (without LRM): !DNUOF TON "ext.ELIFYM\1RID\:c" ELIF :err012
- Logical order (with LRM): err012: FILE ">@c:\DIR1@\MYFILE.ext@^" NOT FOUND!
- Display (without LRM): !DNUOF TON "c:\1RID\ELIFYM.ext" ELIF :err012
-</pre>
--->
-<p> </p>
-
-
-</BODY>
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
+<HEAD>
+
+<meta name="copyright" content="Copyright (c) IBM Corporation and others 2012. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
+
+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
+<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
+
+<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
+<TITLE>Supported Text Types</TITLE>
+
+<link rel="stylesheet" type="text/css" HREF="../book.css">
+</HEAD>
+<BODY BGCOLOR="#ffffff">
+
+<h2>Supported Text Types</h2>
+<p>Out-of-the-box we include support for the following text types:</p>
+<ul>
+ <li><a href="#comma">Comma-delimited List</a></li>
+<!-- missing: <li><a href="#email">e-mail address</a></li> -->
+ <li><a href="#file">Full Path - Relative Path - File Name</a></li>
+ <li><a href="#java">Java Code</a></li>
+ <li><a href="#regex">Regular Expression</a></li>
+<!-- missing: <li><a href="#sql">SQL statement</a></li> -->
+ <li><a href="#underscore">Compound Name with Underscores</a></li>
+ <li><a href="#url">URL, URI, IRI</a></li>
+ <li><a href="#xpath">XPath</a></li>
+
+<!-- dropped:
+ <li><a href="#userid">System, Userid Specification</a></li>
+ <li><a href="#math">Mathematical Formula</a></li>
+ <li><a href="#property">Property File</a></li>
+ <li><a href="#message">Message with Placeholders</a></li>
+-->
+</ul>
+<p>Developers can add custom text types by contributing to the <code>org.eclipse.equinox.bidi.bidiTypes</code>
+extension point.</p>
+<p>Unless specified otherwise, we assume that the relative progression of the tokens and separators for display
+should always be from left to right, while the text of each token will go LTR or
+RTL depending on its content and according to the Unicode Bidirectional Algorithm.</p>
+<p>(In the examples, "<b>@</b>" represents an LRM, "<b>&</b>" represents an RLM.)</p>
+
+<h3><a name="comma"></a>Comma-delimited List (<code>comma</code>)</h3>
+<h4>Pattern</h4>
+<p><span style="color:blue">[first list item]</span> <span style="color:red"><b>
+,</b></span> <span style="color:blue">[second list item]</span>
+<span style="color:red"><b>,</b></span> <span style="color:blue">. . .</span>
+<span style="color:red"><b>,</b></span> <span style="color:blue">[last list
+item]</span> </p>
+<h4>Detailed Design</h4>
+<p>The general algorithm applies, with the
+following adaptations:</p>
+<ul>
+ <li>There is only one separator, the comma(,). </li>
+ <li>This design can easily be adapted to accomodate a different separator,
+ like a semicolon (;) or a tab character, etc... </li>
+</ul>
+<b>Example:</b>
+<pre> Logical order (without LRM): ABC,DE,FGH
+ Display (without LRM): HGF,ED,CBA
+ Logical order (with LRM): ABC@,DE@,FGH
+ Display (without LRM): CBA,ED,HGF
+</pre>
+
+<h3><a name="file"></a>Name or Path of File or Directory </h3>
+<h4>Patterns</h4>
+<p><u>Windows full path:</u> <span style="color:blue">[drive letter]</span><span style="color:red"><b>:\</b></span>
+<span style="color:blue">[sub-path]</span> <span style="color:red"><b>\</b></span>
+<span style="color:blue">. . .</span> <span style="color:red"><b>\</b></span>
+<span style="color:blue">[sub-path]</span></p>
+<p><u>Windows relative path:</u> <span style="color:blue">[sub-path]</span>
+<span style="color:red"><b>\</b></span> <span style="color:blue">. . .</span>
+<span style="color:red"><b>\</b></span> <span style="color:blue">[sub-path]</span></p>
+<p><u>Windows full file path:</u> <span style="color:blue">[drive letter]</span><span style="color:red"><b>:\</b></span>
+<span style="color:blue">[sub-path]</span> <span style="color:red"><b>\</b></span>
+<span style="color:blue">. . .</span> <span style="color:red"><b>\</b></span>
+<span style="color:blue">[sub-path]</span> <span style="color:red"><b>\</b></span>
+<span style="color:blue">[file name]</span> <span style="color:red"><b>.</b></span>
+<span style="color:blue">[extension]</span></p>
+<p><u>Windows relative file path:</u> <span style="color:blue">[sub-path]</span>
+<span style="color:red"><b>\</b></span> <span style="color:blue">. . .</span>
+<span style="color:red"><b>\</b></span> <span style="color:blue">[sub-path]</span>
+<span style="color:red"><b>\</b></span> <span style="color:blue">[file name]</span>
+<span style="color:red"><b>.</b></span> <span style="color:blue">[extension]</span></p>
+<p><u>Linux full path:</u> <span style="color:red"><b>/</b></span>
+<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
+<span style="color:blue">. . .</span> <span style="color:red"><b>/</b></span>
+<span style="color:blue">[sub-path]</span></p>
+<p><u>Linux relative path:</u> <span style="color:blue">[sub-path]</span>
+<span style="color:red"><b>/</b></span> <span style="color:blue">. . .</span>
+<span style="color:red"><b>/</b></span> <span style="color:blue">[sub-path]</span></p>
+<p><u>Linux full file path:</u> <span style="color:red"><b>/</b></span>
+<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
+<span style="color:blue">. . .</span> <span style="color:red"><b>/</b></span>
+<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
+<span style="color:blue">[file name]</span> <span style="color:red"><b>.</b></span>
+<span style="color:blue">[extension]</span></p>
+<p><u>Linux relative file path:</u> <span style="color:blue">[sub-path]</span>
+<span style="color:red"><b>/</b></span> <span style="color:blue">. . .</span>
+<span style="color:red"><b>/</b></span> <span style="color:blue">[sub-path]</span>
+<span style="color:red"><b>/</b></span> <span style="color:blue">[file name]</span>
+<span style="color:red"><b>.</b></span> <span style="color:blue">[extension]</span></p>
+<h4>Detailed Design</h4>
+<p>The general algorithm applies, with the
+following adaptation:</p>
+<ul>
+ <li>The separators are colon (:), backslash (\) and full stop (.) for
+ Windows, slash (/) and full stop (.) for Linux. </li>
+</ul>
+<b>Example:</b>
+<pre> Logical order (without LRM): c:\DIR1\DIR2\MYFILE.ext
+ Display (without LRM): c:\ELIFYM\2RID\1RID.ext
+ Logical order (with LRM): c:\DIR1@\DIR2@\MYFILE.ext
+ Display (without LRM): c:\1RID\2RID\ELIFYM.ext
+</pre>
+
+<h3><a name="java"></a>Java Code</h3>
+<h4>Requirement</h4>
+<p>We can classify elements of a Java program as: </p>
+<ul>
+ <li>white space </li>
+ <li>operators </li>
+ <li>String literals: they start with a double quote and end with a double
+ quote which is not escaped (not preceded by a backslash). </li>
+ <li>comments: they start with /* and end with */ or start with // and end at
+ the end of the line. </li>
+ <li>tokens: anything delimited by the previous items. </li>
+</ul>
+<p>The requirement is to make the relative order of elements left-to-right,
+while each element by itself will be presented according to the Unicode Bidirectional Algorithm. </p>
+<h4>Detailed Design</h4>
+<p>The general algorithm applies, with the
+following adaptations:</p>
+<ul>
+ <li>Each String literal or comment is considered as one token. </li>
+ <li>The separators are all the characters used as operators and separators
+ in the Java language: plus (+), minus (-), asterisk (*), slash (/), percent
+ (%), less-than (<), greater-than (>), ampersand (&), vertical bar (|),
+ circumflex (^), tilde (~), left and right parentheses ( ( ) ), left and
+ right square brackets ([ ]), left and right curly brackets ( { } ), comma
+ (,), full stop (.), semicolon (;), exclamation mark (!), question mark (?),
+ colon (:), spaces which are not part of a String literal or a comment. </li>
+ <li>If a String literal or a comment includes LRE or RLE characters but do
+ not include the proper number of matching PDF characters, missing PDF
+ characters must be added at the end of the literal or comment.</li>
+</ul>
+<b>Example:</b>
+<pre> Logical order (without LRM): A = /*B+C*/ D;
+ Display (without LRM): D /*C+B*/ = A;
+ Logical order (with LRM): A@ = /*B+C@*/ D;
+ Display (without LRM): A = /*C+B*/ D;
+</pre>
+
+<h3><a name="regex"></a>Regular Expression</h3>
+<h4>Requirement</h4>
+<p>Preserve the relative order of the regular expression components identical to
+the order in which they appear when exclusively Latin characters are used.</p>
+<h4>Detailed Design</h4>
+<p>The general algorithm applies, with the
+following adaptations:</p>
+<ul>
+ <li>Regular expressions consist of operators, pattern characters, and
+ " in most implementations of extended syntax " named identifiers.</li>
+ <li>Since the syntax of regular expression is not standardized, the
+ list of operators should be adapted to the specific implementation at hand.
+ </li>
+ <li>Common operators include: question mark (?), circumflex (^), dollar ($), plus
+ (+), minus (-), asterisk (*), vertical bar (|), tilde (~), left and right
+ parentheses ( ( ) ), left and right square brackets ([ ]), left and right
+ curly brackets ( { } ), commercial at (@), number sign (#), ampersand (&),
+ backslash (\).</li>
+ <li>The separators will be the characters used as operators for regular
+ expressions.</li>
+ <li>Characters which are not operators are pattern characters.
+ If an operator is immediately preceded by a backslash, both the
+ backslash and the operator must be handled as pattern characters.</li>
+ <li>Each pattern character is a separate token, so pattern characters
+ will always be ordered according to the base text direction of the
+ expression.</li>
+ <li>Identifiers appear in certain syntactic constructs, and are treated as
+ tokens. For example, the strings "digit" and "number" in the expression
+ "total: (?<number>[:digit:]+)\s" are identifiers, whereas "total" is just
+ a sequence of 5 pattern characters.</li>
+ <li>The following constructs must be recognized as delimiting tokens
+ (note: this list should be adapted to the specific syntax of regular
+ expressions in a given environment):<br>
+ (?<name><br>
+ (?'name'<br>
+ (?(<name>)<br>
+ (?('name')<br>
+ (?(name)<br>
+ (?&name)<br>
+ (?P<name><br>
+ \k<name><br>
+ \k'name'<br>
+ \k{name}<br>
+ (?P=name)<br>
+ \g{name}<br>
+ \g<name><br>
+ \g'name'<br>
+ (?(R&name)<br>
+ [:class:]<br>
+ </li>
+ <li>Comments of the form (?# . . . ) must be handled as individual tokens.</li>
+ <li>Quoted sequences of the form \Q . . . \E must be handled as individual tokens.</li>
+ <li>Numbers used as quantifiers (numbers of occurrences) or as group references
+ must be handled as individual tokens.</li>
+ <li>If the first strong directional character in a regular expression is an
+ Arabic letter, the base direction of the expression must be RTL.</li>
+ <li>If the first strong directional character in a regular expression is a
+ Hebrew letter or a LTR letter, the base direction of the expression must be
+ LTR.</li>
+ <li>If the regular expression contains no strong directional character, its
+ base direction must be LTR for Hebrew users. For Arabic users, its base
+ direction should follow the user interface direction (RTL if mirrored, LTR otherwise).</li>
+</ul>
+<b>Example (Hebrew):</b>
+<pre> Logical order (without LRM): ABC(?'DEF'GHI
+ Display (without LRM): IHG'FED'?(CBA
+ Logical order (with LRM): A@B@C@(?'DEF'@G@H@I
+ Display (without LRM): ABC(?'FED'GHI
+</pre>
+<b>Example (Arabic):</b>
+<pre> Logical order (without LRM): ABC(?'DEF'GHI
+ Display (without LRM): IHG'FED'?(CBA
+ Logical order (with LRM): ABC(?'DEF'GHI
+ Display (without LRM): IHG'FED'?(CBA
+</pre>
+
+<h3><a name="underscore"></a>Compound Name with Underscores</h3>
+<h4>Pattern</h4>
+<p><span style="color:blue">[first part]</span> <span style="color:red"><b>_</b></span>
+<span style="color:blue">[second part]</span> <span style="color:red"><b>_</b></span>
+<span style="color:blue">[third part]</span> </p>
+<p>Note: name parts must not include underscores.</p>
+<h4>Detailed Design</h4>
+<p>The general algorithm applies, with the
+following adaptation:</p>
+<ul>
+ <li>There is only one separator, the underscore (_). </li>
+</ul>
+<b>Example:</b>
+<pre> Logical order (without LRM): MYPACKAGE_MYPROGRAM
+ Display (without LRM): MARGORPYM_EGAKCAPYM
+ Logical order (with LRM): MYPACKAGE@_MYPROGRAM
+ Display (without LRM): EGAKCAPYM_MARGORPYM
+</pre>
+
+<h3><a name="url"></a>URL, URI, IRI</h3>
+<h4>Patterns</h4>
+<p><span style="color:red"><b>http://</b></span> <span style="color:blue">
+[domain label]</span> <span style="color:red"><b>.</b></span>
+<span style="color:blue">. . .</span> <span style="color:red"><b>.</b></span>
+<span style="color:blue">[domain label]</span></p>
+<p><span style="color:red"><b>http://</b></span> <span style="color:blue">
+[domain label]</span> <span style="color:red"><b>.</b></span>
+<span style="color:blue">. . .</span> <span style="color:red"><b>.</b></span>
+<span style="color:blue">[domain label]</span> <span style="color:red"><b>/</b></span>
+<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
+<span style="color:blue">. . .</span> <span style="color:red"><b>/</b></span>
+<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
+<span style="color:blue">[file name]</span> <span style="color:red"><b>.</b></span>
+<span style="color:blue">[extension]</span></p>
+<p><span style="color:red"><b>http://</b></span> <span style="color:blue">
+[domain label]</span> <span style="color:red"><b>.</b></span>
+<span style="color:blue">. . .</span> <span style="color:red"><b>.</b></span>
+<span style="color:blue">[domain label]</span> <span style="color:red"><b>/</b></span>
+<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
+<span style="color:blue">. . .</span> <span style="color:red"><b>/</b></span>
+<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
+<span style="color:blue">[file name]</span> <span style="color:red"><b>.</b></span>
+<span style="color:blue">[extension]</span> <span style="color:red"><b>#</b></span>
+<span style="color:blue">[local reference]</span> </p>
+<p><span style="color:red"><b>http://</b></span> <span style="color:blue">
+[domain label]</span> <span style="color:red"><b>.</b></span>
+<span style="color:blue">. . .</span> <span style="color:red"><b>.</b></span>
+<span style="color:blue">[domain label]</span> <span style="color:red"><b>/</b></span>
+<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
+<span style="color:blue">. . .</span> <span style="color:red"><b>/</b></span>
+<span style="color:blue">[sub-path]</span> <span style="color:red"><b>/</b></span>
+<span style="color:blue">[file name]</span> <span style="color:red"><b>.</b></span>
+<span style="color:blue">[extension]</span> <span style="color:red"><b>?</b></span>
+<span style="color:blue">[key1]</span> <span style="color:red"><b>=</b></span>
+<span style="color:blue">[value1]</span> <span style="color:red"><b>&</b></span>
+<span style="color:blue">[key2]</span> <span style="color:red"><b>=</b></span>
+<span style="color:blue">[value2]</span></p>
+<h4>Detailed Design</h4>
+<p>The general algorithm applies, with the
+following adaptations:</p>
+<ul>
+ <li>The detailed syntax of URLs, URIs, IRIs is described in
+ <a href="http://www.ietf.org/rfc/rfc3986.txt">RFC 3986</a> and
+ <a href="http://www.ietf.org/rfc/rfc3987.txt">RFC 3987</a>. A rigorous
+ analysis to identify tokens and separators is not simple. </li>
+ <li>For most practical cases, it is sufficient to consider the following
+ separators: colon (:), question mark (?), number sign (#), slash (/),
+ commercial at (@), full stop (.), left bracket ([), right bracket (]). </li>
+</ul>
+<b>Example:</b>
+<pre> Logical order (without LRM): www.DOC.MYDOMAIN.com\HEB\LESSON1.html
+ Display (without LRM): www.NIAMODYM.COD.com\1NOSSEL\BEH.html
+ Logical order (with LRM): www.DOC@.MYDOMAIN.com\HEB@\LESSON1.html
+ Display (without LRM): www.COD.NIAMODYM.com\BEH\1NOSSEL.html
+</pre>
+
+<h3><a name="xpath"></a>XPath</h3>
+<h4>Patterns</h4>
+<p><span style="color:red"><b>/</b></span> <span style="color:blue">book</span>
+<span style="color:red"><b>/</b></span> <span style="color:blue">chapter</span>
+<span style="color:red"><b>/</b></span> <span style="color:blue">paragraph</span></p>
+<p><span style="color:red"><b>/</b></span> <span style="color:blue">year</span>
+<span style="color:red"><b>/</b></span> <span style="color:blue">month</span>
+<span style="color:red"><b>[@</b></span><span style="color:blue">name</span>
+<span style="color:red"><b>=</b></span> <span style="color:red"><b>"</b></span><span style="color:blue">April</span><span style="color:red"><b>"]</b></span>
+</p>
+<h4>Detailed Design</h4>
+<p>The general algorithm applies, with the
+following adaptations:</p>
+<ul>
+ <li><b><u>Strings</u></b>
+ <ul>
+ <li>Strings are started by a <i>quotation mark</i> which can be a
+ double-quote (") or an apostrophe ('), and are closed by the same
+ character. </li>
+ <li>Double-quotes may appear within a string limited by apostrophes and
+ vice versa, and must be handled as characters internal to the string.
+ </li>
+ <li>A string started on one line is not necessarily closed on the same
+ line.</li>
+ </ul>
+ </li>
+ <li><b><u>Whitespace</u></b> (e.g. blanks and tab characters) appearing
+ outside of strings constitutes a delimiter for tokens.
+ </li>
+ <li>Each occurrence of a string must be handled as one token.
+ </li>
+ <li>After isolating strings, the following characters are separators: white
+ space, slash (/), square brackets ( [ and ] ), less-than (<), greater-than
+ (>), equal sign (=), exclamation mark (!), colon (:), at sign (@), period
+ (.), vertical bar (|), parentheses ( ( and ) ), plus (+), minus (-),
+ asterisk (*).
+ </li>
+ <li>Some operators are words like "and", "or", "div", "mod". For our
+ purpose, they can be handled as tokens.
+ </li>
+ <li>Some operators are represented by a pair of symbols like "not equal"
+ (!=), "descendant-or-self" (//), "parent" (..). For our purpose, they can be
+ handled as 2 successive operators represented by one symbol each. </li>
+</ul>
+<b>Example:</b>
+<pre> Logical order (without LRM): DEF!GHI 'A!B'=JK
+ Display (without LRM): KJ='B!A' IHG!FED
+ Logical order (with LRM): DEF@!GHI@ 'A!B'@=JK
+ Display (without LRM): FED!IHG 'B!A'=KJ
+</pre>
+
+<!-- dropped:
+<h3><a name="property"></a>Property File</h3>
+<h4>Pattern</h4>
+<p><span style="color:blue">[variable name]</span> <span style="color:red"><b>=</b></span>
+<span style="color:blue">[value]</span> </p>
+<p>Note: variable names must not include equal signs.</p>
+<h4>Detailed Design</h4>
+<p>The general algorithm applies, with the
+following adaptations:</p>
+<ul>
+ <li>There is only one separator, the equal sign (=).</li>
+ <li>It is enough to locate the first occurrence of the separator. Everything
+ before can be considered as the first token, everything after can be
+ considered the second (and last) token.</li>
+</ul>
+<b>Example:</b>
+<pre> Logical order (without LRM): PRIORITY=5
+ Display (without LRM): 5=YTIROIRP
+ Logical order (with LRM): PRIORITY@=5
+ Display (without LRM): YTIROIRP=5
+</pre>
+
+<h3><a name="userid"></a>System, Userid Specification</h3>
+<h4>Pattern</h4>
+<p><span style="color:blue">[system ID]</span> <span style="color:red"><b>(</b></span>
+<span style="color:blue">[user ID]</span> <span style="color:red"><b>)</b></span>
+</p>
+<p>Note: the system ID must not include parentheses.</p>
+<h4>Detailed Design</h4>
+<p>The general algorithm applies, with the
+following adaptations:</p>
+<ul>
+ <li>It is enough to consider one separator, the left parenthesis ( ( ). </li>
+ <li>It is enough to locate the first occurrence of the separator. Everything
+ before can be considered as the first token, everything after can be
+ considered the second (and last) token. </li>
+</ul>
+<b>Example:</b>
+<pre> Logical order (without LRM): MY_HOST(MY_USERID)
+ Display (without LRM): DIRESU_YM)TSOH_YM)
+ Logical order (with LRM): MY_HOST@(MY_USERID)
+ Display (without LRM): TSOH_YM(DIRESU_YM)
+</pre>
+
+<h3><a name="math"></a>Mathematical Formula</h3>
+<h4>Requirement</h4>
+<p>Preserve the relative order of the formula components according to the
+base text direction of the formula.</p>
+<h4>Detailed Design</h4>
+<p>The general algorithm applies, with the
+following adaptations:</p>
+<ul>
+ <li>The separators are the usual arithmetic operators. </li>
+ <li>Tokens will be ordered according to the base text direction of the
+ formula.</li>
+ <li>If the first strong directional character in the formula is a Hebrew or
+ LTR letter, the base text direction of the formula is LTR.</li>
+ <li>If the first strong directional character in the formula is an
+ Arabic letter, the base direction of the formula must be RTL.</li>
+ <li>If there is no strong directional character in the formula but there are
+ Arabic-Indic digits, the base direction of the formula must be
+ RTL, otherwise it must be LTR.</li>
+</ul>
+<b>Example (Hebrew):</b>
+<pre> Logical order (without LRM): PROFIT = REVENUE - COST
+ Display (without LRM): TSOC - EUNEVER = TIFORP
+ Logical order (with LRM): PROFIT @= REVENUE @- COST
+ Display (without LRM): TIFORP = EUNEVER - TSOC
+</pre>
+<b>Example (Arabic, ampersand represents RLM):</b>
+<pre> Logical order (without LRM): DIVIDEND = SHARE x 0.10
+ Display (without LRM): x 0.10 ERAHS = DNEDIVID
+ Logical order (with LRM): DIVIDEND = SHARE x& 0.10
+ Display (without LRM): 0.10 x ERAHS = DNEDIVID
+</pre>
+
+<h3><a name="message"></a>Message with Placeholders</h3>
+<p>Products often use template messages where placeholders are replaced by
+custom data at run time.</p>
+<h4>Requirement</h4>
+<p>The display considerations must ensure correct presentation of both the
+template text and the custom data replacing the placeholders, taking in account
+that these data might have an internal structure, which should be preserved.</p>
+<h4>Detailed Design</h4>
+<ol>
+ <li>The message template will be considered as having a LTR base direction
+ if it is not translated, a RTL base direction if it is translated to Arabic
+ or Hebrew.</li>
+ <li>Let us call "insertion unit" a piece of custom data which is to replace
+ a placeholder. Insertion units with an internal structure also have a
+ defined base direction, generally LTR. For insertion units without internal
+ structure, their base direction will be defined as RTL if they contain at
+ least one Arabic or Hebrew letter, LTR otherwise.</li>
+ <li> Each insertion unit with an internal structure must be processed
+ according to its specific structure.</li>
+ <li>If the base direction of an insertion unit is the same as that of the
+ template, there is nothing more to do for it.</li>
+ <li>If the base direction of the template is LTR and the
+ base direction of an insertion unit is RTL, the insertion unit should have
+ RLE+RLM added at its beginning and RLM+PDF added at its end.</li>
+ <li>If the base direction of the template is RTL and the
+ base direction of an insertion unit is LTR, the insertion unit should have
+ LRE+LRM added at its beginning and LRM+PDF added at its end.</li>
+ <li>If the component in which the formatted message is
+ displayed has an orientation different from the template direction, the formatted
+ message must have LRE+LRM added to its beginning and LRM+PDF added to its
+ end if its base direction is LTR, RLE+RLM added to its beginning and
+ RLM+PDF added to its end if its base direction is RTL.</li>
+</ol>
+<b>Example</b> (">" represents LRE, "^" represents PDF, "@" represents LRM)<b>:</b>
+<pre> Logical order (template without LRM): err012: FILE "%1" NOT FOUND!
+ Logical order (%1 without LRM): c:\DIR1\MYFILE.ext
+ Display (without LRM): !DNUOF TON "ext.ELIFYM\1RID\:c" ELIF :err012
+ Logical order (with LRM): err012: FILE ">@c:\DIR1@\MYFILE.ext@^" NOT FOUND!
+ Display (without LRM): !DNUOF TON "c:\1RID\ELIFYM.ext" ELIF :err012
+</pre>
+-->
+<p> </p>
+
+
+</BODY>
</HTML>
\ No newline at end of file
diff --git a/bundles/org.eclipse.platform.doc.isv/schema.css b/bundles/org.eclipse.platform.doc.isv/schema.css
index 10aee31..fb2028d 100644
--- a/bundles/org.eclipse.platform.doc.isv/schema.css
+++ b/bundles/org.eclipse.platform.doc.isv/schema.css
@@ -1,71 +1,71 @@
-/*******************************************************************************
- * Copyright (c) 2003 IBM Corporation and others.
- * All rights reserved. This program and the accompanying materials
- * are made available under the terms of the Eclipse Public License v1.0
- * which accompanies this distribution, and is available at
- * http://www.eclipse.org/legal/epl-v10.html
- *
- * Contributors:
- * IBM Corporation - initial API and implementation
- *******************************************************************************/
-
-H6.SchemaHeader {
- font-size:16px;
- display:inline
-}
-
-P.SchemaCopyright {
- font-size: smaller;
- font-style: normal;
- color: #336699;
- display:inline;
- margin-top: 3.000000pt;
- margin-bottom: 11.000000pt;
- margin-right: 0.000000pt;
- margin-left: 0.000000pt;
-}
-
-P.SchemaDtd {
- color: #800000;
- margin-top: 0.000000pt;
- margin-bottom: 0.000000pt;
- margin-right: 0.000000pt;
- margin-left: 10.000000pt;
-}
-
-P.SchemaDtdAttlist {
- color: #800000;
- margin-top: 0.000000pt;
- margin-bottom: 0.000000pt;
- margin-right: 0.000000pt;
- margin-left: 20.000000pt;
-}
-
-span.SchemaTag {
- color: #000080;
-}
-
-span.SchemaCstring {
- color: #008000;
-}
-
-pre.Example {
- margin-top: 0.000000pt;
-}
-
-.ConfigMarkupElementDesc {
- color: black;
- margin-top: 0.000000pt;
- margin-bottom: 0.000000pt;
- margin-right: 0.000000pt;
- margin-left: 10.000000pt;
-}
-
-.ConfigMarkupAttlistDesc {
- color: black;
- margin-top: 0.000000pt;
- margin-bottom: 0.000000pt;
- margin-right: 0.000000pt;
- margin-left: 32.000000pt;
-}
-
+/*******************************************************************************
+ * Copyright (c) 2003 IBM Corporation and others.
+ * All rights reserved. This program and the accompanying materials
+ * are made available under the terms of the Eclipse Public License v1.0
+ * which accompanies this distribution, and is available at
+ * http://www.eclipse.org/legal/epl-v10.html
+ *
+ * Contributors:
+ * IBM Corporation - initial API and implementation
+ *******************************************************************************/
+
+H6.SchemaHeader {
+ font-size:16px;
+ display:inline
+}
+
+P.SchemaCopyright {
+ font-size: smaller;
+ font-style: normal;
+ color: #336699;
+ display:inline;
+ margin-top: 3.000000pt;
+ margin-bottom: 11.000000pt;
+ margin-right: 0.000000pt;
+ margin-left: 0.000000pt;
+}
+
+P.SchemaDtd {
+ color: #800000;
+ margin-top: 0.000000pt;
+ margin-bottom: 0.000000pt;
+ margin-right: 0.000000pt;
+ margin-left: 10.000000pt;
+}
+
+P.SchemaDtdAttlist {
+ color: #800000;
+ margin-top: 0.000000pt;
+ margin-bottom: 0.000000pt;
+ margin-right: 0.000000pt;
+ margin-left: 20.000000pt;
+}
+
+span.SchemaTag {
+ color: #000080;
+}
+
+span.SchemaCstring {
+ color: #008000;
+}
+
+pre.Example {
+ margin-top: 0.000000pt;
+}
+
+.ConfigMarkupElementDesc {
+ color: black;
+ margin-top: 0.000000pt;
+ margin-bottom: 0.000000pt;
+ margin-right: 0.000000pt;
+ margin-left: 10.000000pt;
+}
+
+.ConfigMarkupAttlistDesc {
+ color: black;
+ margin-top: 0.000000pt;
+ margin-bottom: 0.000000pt;
+ margin-right: 0.000000pt;
+ margin-left: 32.000000pt;
+}
+
diff --git a/bundles/org.eclipse.platform.doc.user/images/info_obj.svg b/bundles/org.eclipse.platform.doc.user/images/info_obj.svg
index e8a3128..b8fe8cc 100644
--- a/bundles/org.eclipse.platform.doc.user/images/info_obj.svg
+++ b/bundles/org.eclipse.platform.doc.user/images/info_obj.svg
@@ -1,182 +1,182 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!-- Created with Inkscape (http://www.inkscape.org/) -->
-
-<svg
- xmlns:dc="http://purl.org/dc/elements/1.1/"
- xmlns:cc="http://creativecommons.org/ns#"
- xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
- xmlns:svg="http://www.w3.org/2000/svg"
- xmlns="http://www.w3.org/2000/svg"
- xmlns:xlink="http://www.w3.org/1999/xlink"
- xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
- xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
- width="16"
- height="16"
- id="svg2"
- version="1.1"
- inkscape:version="0.48.5 r10040"
- sodipodi:docname="info_obj.svg">
- <defs
- id="defs4">
- <linearGradient
- inkscape:collect="always"
- id="linearGradient4996">
- <stop
- style="stop-color:#02468c;stop-opacity:1"
- offset="0"
- id="stop4998" />
- <stop
- style="stop-color:#0e62a4;stop-opacity:1"
- offset="1"
- id="stop5000" />
- </linearGradient>
- <linearGradient
- inkscape:collect="always"
- xlink:href="#linearGradient4996"
- id="linearGradient5002"
- x1="13.903196"
- y1="1062.1353"
- x2="13.903196"
- y2="1051.7347"
- gradientUnits="userSpaceOnUse"
- gradientTransform="translate(2,0)" />
- <linearGradient
- inkscape:collect="always"
- id="linearGradient4996-4">
- <stop
- style="stop-color:#02468c;stop-opacity:1"
- offset="0"
- id="stop4998-5" />
- <stop
- style="stop-color:#0e62a4;stop-opacity:1"
- offset="1"
- id="stop5000-5" />
- </linearGradient>
- <linearGradient
- y2="1051.7347"
- x2="13.903196"
- y1="1062.1353"
- x1="13.903196"
- gradientTransform="translate(38.469436,55.035191)"
- gradientUnits="userSpaceOnUse"
- id="linearGradient5028"
- xlink:href="#linearGradient4996-4"
- inkscape:collect="always" />
- <linearGradient
- inkscape:collect="always"
- xlink:href="#linearGradient4996"
- id="linearGradient2996"
- gradientUnits="userSpaceOnUse"
- gradientTransform="matrix(0.97704778,0,0,1,2.2500552,0)"
- x1="13.903196"
- y1="1062.1353"
- x2="13.903196"
- y2="1051.7347" />
- <linearGradient
- inkscape:collect="always"
- xlink:href="#linearGradient4996-8"
- id="linearGradient2996-2"
- gradientUnits="userSpaceOnUse"
- gradientTransform="matrix(0.97704778,0,0,1,2.2500552,0)"
- x1="13.903196"
- y1="1062.1353"
- x2="13.903196"
- y2="1051.7347" />
- <linearGradient
- id="linearGradient4996-8">
- <stop
- style="stop-color:#ffffff;stop-opacity:1;"
- offset="0"
- id="stop4998-51" />
- <stop
- style="stop-color:#ffffff;stop-opacity:0;"
- offset="1"
- id="stop5000-6" />
- </linearGradient>
- <linearGradient
- y2="1057.5728"
- x2="14.694597"
- y1="1057.5728"
- x1="16.1101"
- gradientTransform="matrix(0.97704778,0,0,1,2.250055,-1.0000001e-6)"
- gradientUnits="userSpaceOnUse"
- id="linearGradient3798"
- xlink:href="#linearGradient4996-8"
- inkscape:collect="always" />
- </defs>
- <sodipodi:namedview
- id="base"
- pagecolor="#ffffff"
- bordercolor="#666666"
- borderopacity="1.0"
- inkscape:pageopacity="0.0"
- inkscape:pageshadow="2"
- inkscape:zoom="31.999999"
- inkscape:cx="4.1275963"
- inkscape:cy="8.047133"
- inkscape:document-units="px"
- inkscape:current-layer="text4140-1-8"
- showgrid="true"
- inkscape:window-width="1171"
- inkscape:window-height="959"
- inkscape:window-x="277"
- inkscape:window-y="450"
- inkscape:window-maximized="0"
- showguides="true"
- inkscape:guide-bbox="true"
- inkscape:snap-global="false">
- <inkscape:grid
- type="xygrid"
- id="grid4099" />
- </sodipodi:namedview>
- <metadata
- id="metadata7">
- <rdf:RDF>
- <cc:Work
- rdf:about="">
- <dc:format>image/svg+xml</dc:format>
- <dc:type
- rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
- <dc:title />
- </cc:Work>
- </rdf:RDF>
- </metadata>
- <g
- inkscape:label="Layer 1"
- inkscape:groupmode="layer"
- id="layer1"
- style="display:inline"
- transform="translate(0,-1036.3622)">
- <g
- style="display:inline"
- id="g8159"
- transform="translate(-8.2201163,-12.904699)">
- <g
- style="font-size:15.07241726px;font-style:normal;font-variant:normal;font-weight:900;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:url(#linearGradient5002);fill-opacity:1;stroke:none;display:inline;font-family:Kozuka Mincho Pr6N H;-inkscape-font-specification:Kozuka Mincho Pr6N H Heavy"
- id="text4140-1-8">
- <path
- d="m 16.168743,1050.9177 c -0.347298,0.01 -0.635687,0.1291 -0.86517,0.3674 -0.229485,0.2383 -0.348523,0.5529 -0.357112,0.9439 0.0086,0.3981 0.127627,0.7172 0.357113,0.9571 0.229482,0.2399 0.517871,0.363 0.865169,0.3692 0.354348,-0.01 0.647032,-0.1293 0.878054,-0.3692 0.231015,-0.2399 0.350665,-0.559 0.358954,-0.9571 -0.0056,-0.3778 -0.119655,-0.6886 -0.342387,-0.9326 -0.222739,-0.244 -0.520945,-0.3702 -0.894621,-0.3787 z m 0.927756,3.3912 c -1.016117,0.4346 -1.973323,0.6808 -2.871626,0.7386 l 0,0.6029 c 0.425835,-0.02 0.693362,0.039 0.802582,0.1771 0.109219,0.1381 0.155852,0.476 0.139901,1.0136 l 0,3.4515 c 0.01504,0.5401 -0.03345,0.888 -0.145422,1.0438 -0.111982,0.1557 -0.377669,0.2248 -0.797061,0.2072 l 0,0.633 3.990823,0 0,-0.633 c -0.377672,0.017 -0.620042,-0.051 -0.727111,-0.2054 -0.107076,-0.1541 -0.154322,-0.4977 -0.141739,-1.0305 l 0,-5.8631 z"
- style="fill:url(#linearGradient2996)"
- id="path5058"
- inkscape:connector-curvature="0" />
- <path
- d="m 16.168743,1050.9177 c -0.347298,0.01 -0.635687,0.1291 -0.86517,0.3674 -0.229485,0.2383 -0.348523,0.5529 -0.357112,0.9439 0.0086,0.3981 0.127627,0.7172 0.357113,0.9571 0.229482,0.2399 0.517871,0.363 0.865169,0.3692 0.354348,-0.01 0.647032,-0.1293 0.878054,-0.3692 0.231015,-0.2399 0.350665,-0.559 0.358954,-0.9571 -0.0056,-0.3778 -0.119655,-0.6886 -0.342387,-0.9326 -0.222739,-0.244 -0.520945,-0.3702 -0.894621,-0.3787 z m 0.927756,3.3912 c -1.016117,0.4346 -1.973323,0.6808 -2.871626,0.7386 l 0,0.6029 c 0.425835,-0.02 0.693362,0.039 0.802582,0.1771 0.109219,0.1381 0.155852,0.476 0.139901,1.0136 l 0,3.4515 c 0.01504,0.5401 -0.03345,0.888 -0.145422,1.0438 -0.111982,0.1557 -0.377669,0.2248 -0.797061,0.2072 l 0,0.633 3.990823,0 0,-0.633 c -0.377672,0.017 -0.620042,-0.051 -0.727111,-0.2054 -0.107076,-0.1541 -0.154322,-0.4977 -0.141739,-1.0305 l 0,-5.8631 z"
- style="font-size:15.07241725999999993px;font-style:normal;font-variant:normal;font-weight:900;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:url(#linearGradient3798);fill-opacity:1;stroke:none;display:inline;font-family:Kozuka Mincho Pr6N H;-inkscape-font-specification:Kozuka Mincho Pr6N H Heavy"
- id="path5058-7"
- inkscape:connector-curvature="0" />
- </g>
- <text
- xml:space="preserve"
- style="font-size:15.07241726px;font-style:normal;font-variant:normal;font-weight:900;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:url(#linearGradient5028);fill-opacity:1;stroke:none;display:inline;font-family:Kozuka Mincho Pr6N H;-inkscape-font-specification:Kozuka Mincho Pr6N H Heavy"
- x="50.288464"
- y="1117.2119"
- id="text4140-1-8-1"
- sodipodi:linespacing="125%"><tspan
- sodipodi:role="line"
- id="tspan4142-7-8-7"
- x="50.288464"
- y="1117.2119"
- style="fill:url(#linearGradient5028);fill-opacity:1">Kozuka Mincho Pr6N H</tspan></text>
- </g>
- </g>
-</svg>
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+ xmlns:dc="http://purl.org/dc/elements/1.1/"
+ xmlns:cc="http://creativecommons.org/ns#"
+ xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+ xmlns:svg="http://www.w3.org/2000/svg"
+ xmlns="http://www.w3.org/2000/svg"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+ xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+ width="16"
+ height="16"
+ id="svg2"
+ version="1.1"
+ inkscape:version="0.48.5 r10040"
+ sodipodi:docname="info_obj.svg">
+ <defs
+ id="defs4">
+ <linearGradient
+ inkscape:collect="always"
+ id="linearGradient4996">
+ <stop
+ style="stop-color:#02468c;stop-opacity:1"
+ offset="0"
+ id="stop4998" />
+ <stop
+ style="stop-color:#0e62a4;stop-opacity:1"
+ offset="1"
+ id="stop5000" />
+ </linearGradient>
+ <linearGradient
+ inkscape:collect="always"
+ xlink:href="#linearGradient4996"
+ id="linearGradient5002"
+ x1="13.903196"
+ y1="1062.1353"
+ x2="13.903196"
+ y2="1051.7347"
+ gradientUnits="userSpaceOnUse"
+ gradientTransform="translate(2,0)" />
+ <linearGradient
+ inkscape:collect="always"
+ id="linearGradient4996-4">
+ <stop
+ style="stop-color:#02468c;stop-opacity:1"
+ offset="0"
+ id="stop4998-5" />
+ <stop
+ style="stop-color:#0e62a4;stop-opacity:1"
+ offset="1"
+ id="stop5000-5" />
+ </linearGradient>
+ <linearGradient
+ y2="1051.7347"
+ x2="13.903196"
+ y1="1062.1353"
+ x1="13.903196"
+ gradientTransform="translate(38.469436,55.035191)"
+ gradientUnits="userSpaceOnUse"
+ id="linearGradient5028"
+ xlink:href="#linearGradient4996-4"
+ inkscape:collect="always" />
+ <linearGradient
+ inkscape:collect="always"
+ xlink:href="#linearGradient4996"
+ id="linearGradient2996"
+ gradientUnits="userSpaceOnUse"
+ gradientTransform="matrix(0.97704778,0,0,1,2.2500552,0)"
+ x1="13.903196"
+ y1="1062.1353"
+ x2="13.903196"
+ y2="1051.7347" />
+ <linearGradient
+ inkscape:collect="always"
+ xlink:href="#linearGradient4996-8"
+ id="linearGradient2996-2"
+ gradientUnits="userSpaceOnUse"
+ gradientTransform="matrix(0.97704778,0,0,1,2.2500552,0)"
+ x1="13.903196"
+ y1="1062.1353"
+ x2="13.903196"
+ y2="1051.7347" />
+ <linearGradient
+ id="linearGradient4996-8">
+ <stop
+ style="stop-color:#ffffff;stop-opacity:1;"
+ offset="0"
+ id="stop4998-51" />
+ <stop
+ style="stop-color:#ffffff;stop-opacity:0;"
+ offset="1"
+ id="stop5000-6" />
+ </linearGradient>
+ <linearGradient
+ y2="1057.5728"
+ x2="14.694597"
+ y1="1057.5728"
+ x1="16.1101"
+ gradientTransform="matrix(0.97704778,0,0,1,2.250055,-1.0000001e-6)"
+ gradientUnits="userSpaceOnUse"
+ id="linearGradient3798"
+ xlink:href="#linearGradient4996-8"
+ inkscape:collect="always" />
+ </defs>
+ <sodipodi:namedview
+ id="base"
+ pagecolor="#ffffff"
+ bordercolor="#666666"
+ borderopacity="1.0"
+ inkscape:pageopacity="0.0"
+ inkscape:pageshadow="2"
+ inkscape:zoom="31.999999"
+ inkscape:cx="4.1275963"
+ inkscape:cy="8.047133"
+ inkscape:document-units="px"
+ inkscape:current-layer="text4140-1-8"
+ showgrid="true"
+ inkscape:window-width="1171"
+ inkscape:window-height="959"
+ inkscape:window-x="277"
+ inkscape:window-y="450"
+ inkscape:window-maximized="0"
+ showguides="true"
+ inkscape:guide-bbox="true"
+ inkscape:snap-global="false">
+ <inkscape:grid
+ type="xygrid"
+ id="grid4099" />
+ </sodipodi:namedview>
+ <metadata
+ id="metadata7">
+ <rdf:RDF>
+ <cc:Work
+ rdf:about="">
+ <dc:format>image/svg+xml</dc:format>
+ <dc:type
+ rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+ <dc:title />
+ </cc:Work>
+ </rdf:RDF>
+ </metadata>
+ <g
+ inkscape:label="Layer 1"
+ inkscape:groupmode="layer"
+ id="layer1"
+ style="display:inline"
+ transform="translate(0,-1036.3622)">
+ <g
+ style="display:inline"
+ id="g8159"
+ transform="translate(-8.2201163,-12.904699)">
+ <g
+ style="font-size:15.07241726px;font-style:normal;font-variant:normal;font-weight:900;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:url(#linearGradient5002);fill-opacity:1;stroke:none;display:inline;font-family:Kozuka Mincho Pr6N H;-inkscape-font-specification:Kozuka Mincho Pr6N H Heavy"
+ id="text4140-1-8">
+ <path
+ d="m 16.168743,1050.9177 c -0.347298,0.01 -0.635687,0.1291 -0.86517,0.3674 -0.229485,0.2383 -0.348523,0.5529 -0.357112,0.9439 0.0086,0.3981 0.127627,0.7172 0.357113,0.9571 0.229482,0.2399 0.517871,0.363 0.865169,0.3692 0.354348,-0.01 0.647032,-0.1293 0.878054,-0.3692 0.231015,-0.2399 0.350665,-0.559 0.358954,-0.9571 -0.0056,-0.3778 -0.119655,-0.6886 -0.342387,-0.9326 -0.222739,-0.244 -0.520945,-0.3702 -0.894621,-0.3787 z m 0.927756,3.3912 c -1.016117,0.4346 -1.973323,0.6808 -2.871626,0.7386 l 0,0.6029 c 0.425835,-0.02 0.693362,0.039 0.802582,0.1771 0.109219,0.1381 0.155852,0.476 0.139901,1.0136 l 0,3.4515 c 0.01504,0.5401 -0.03345,0.888 -0.145422,1.0438 -0.111982,0.1557 -0.377669,0.2248 -0.797061,0.2072 l 0,0.633 3.990823,0 0,-0.633 c -0.377672,0.017 -0.620042,-0.051 -0.727111,-0.2054 -0.107076,-0.1541 -0.154322,-0.4977 -0.141739,-1.0305 l 0,-5.8631 z"
+ style="fill:url(#linearGradient2996)"
+ id="path5058"
+ inkscape:connector-curvature="0" />
+ <path
+ d="m 16.168743,1050.9177 c -0.347298,0.01 -0.635687,0.1291 -0.86517,0.3674 -0.229485,0.2383 -0.348523,0.5529 -0.357112,0.9439 0.0086,0.3981 0.127627,0.7172 0.357113,0.9571 0.229482,0.2399 0.517871,0.363 0.865169,0.3692 0.354348,-0.01 0.647032,-0.1293 0.878054,-0.3692 0.231015,-0.2399 0.350665,-0.559 0.358954,-0.9571 -0.0056,-0.3778 -0.119655,-0.6886 -0.342387,-0.9326 -0.222739,-0.244 -0.520945,-0.3702 -0.894621,-0.3787 z m 0.927756,3.3912 c -1.016117,0.4346 -1.973323,0.6808 -2.871626,0.7386 l 0,0.6029 c 0.425835,-0.02 0.693362,0.039 0.802582,0.1771 0.109219,0.1381 0.155852,0.476 0.139901,1.0136 l 0,3.4515 c 0.01504,0.5401 -0.03345,0.888 -0.145422,1.0438 -0.111982,0.1557 -0.377669,0.2248 -0.797061,0.2072 l 0,0.633 3.990823,0 0,-0.633 c -0.377672,0.017 -0.620042,-0.051 -0.727111,-0.2054 -0.107076,-0.1541 -0.154322,-0.4977 -0.141739,-1.0305 l 0,-5.8631 z"
+ style="font-size:15.07241725999999993px;font-style:normal;font-variant:normal;font-weight:900;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:url(#linearGradient3798);fill-opacity:1;stroke:none;display:inline;font-family:Kozuka Mincho Pr6N H;-inkscape-font-specification:Kozuka Mincho Pr6N H Heavy"
+ id="path5058-7"
+ inkscape:connector-curvature="0" />
+ </g>
+ <text
+ xml:space="preserve"
+ style="font-size:15.07241726px;font-style:normal;font-variant:normal;font-weight:900;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:url(#linearGradient5028);fill-opacity:1;stroke:none;display:inline;font-family:Kozuka Mincho Pr6N H;-inkscape-font-specification:Kozuka Mincho Pr6N H Heavy"
+ x="50.288464"
+ y="1117.2119"
+ id="text4140-1-8-1"
+ sodipodi:linespacing="125%"><tspan
+ sodipodi:role="line"
+ id="tspan4142-7-8-7"
+ x="50.288464"
+ y="1117.2119"
+ style="fill:url(#linearGradient5028);fill-opacity:1">Kozuka Mincho Pr6N H</tspan></text>
+ </g>
+ </g>
+</svg>
