-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathindex.html
152 lines (121 loc) · 6.07 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>Home</title>
<style type="text/css">
.nully-comment {
font-style: italic;
}
.nully-correct {
color: darkgreen;
}
.nully-incorrect {
color: darkred;
}
.nully-error {
/*color: red;*/
border-bottom: 2px dotted #fc0;
}
.nully-anno {
font-weight: bold;
color: #506;
}
code, pre {
font-family: monospace;
}
pre.nully-code {
font-size: 8.5pt;
margin-left: 3em;
margin-right: 3em;
padding: 1em;
background-color: #ffd;
border: 1px solid black;
border-width: 1px 2px 2px 1px;
}
</style>
</head>
<body>
<h4>Introduction</h4>
<p>Nully
is a tool which provides automated edit-time, compile-time, and
run-time checks for <span style="font-style: italic;">illegal</span>
null
values, utilizing Java 5.0 code annotations.</p>
<p style="text-align: center;"><img alt="" src="images/demo.png" style="width: 518px; height: 123px;" /></p>
<p>Nully has four main goals:</p>
<ul>
<li><strong>Ease
of use.</strong> Specifying where
nulls are not allowed is as simple as typing <code>@NonNull</code>
before the variable or method you want to protect.</li>
<li><strong>Security.</strong>
Null values are prevented at run-time using generated null checks in
your compiled code. Your code can safely assume that any values marked
as <code>@NonNull</code>
will not be <code>null</code>,
including local variables, parameters, and returned values from <code>@NonNull</code>
methods. </li>
<li><strong>Documentation.</strong>
Users of your classes know immediately where null values are and are
not allowed, just by looking at the method signature or Javadoc.</li>
<li><strong>Comprehension.</strong>
In-editor illegal null highlighting and compile-time warnings make sure
you understand what your code is doing. </li>
</ul>
<h4>Usage
</h4>
<p>
Nully provides an annotation called <code>@NonNull</code>
which can be applied to method parameters, variables, and return
values, as in the following example:
</p>
<pre class="nully-code"><span class="nully-anno">@NonNull</span> String someMethod(<span class="nully-anno">@NonNull</span> String param) {<br /> <span class="nully-anno">@NonNull</span> String other = "";<br /> return other;<br />}</pre>
<ul>
<li><strong>Method
parameters.</strong> A <code>@NonNull</code>
parameter cannot be passed <code>null</code>.
An exception will be thrown at runtime if a method passes your method a
<code>null</code>
for a <code>@NonNull</code>
parameter, and a warning will be shown if you try to pass <code>null</code>
to such a parameter.
<pre class="nully-code">void takeString(<span class="nully-anno">@NonNull</span> String value) {<br /> <span class="nully-comment">// code can assume value is not null</span><br />}<br />void myMethod() {<br /><span class="nully-comment nully-correct">// CORRECT</span><br />takeString("hi");<br /><span class="nully-comment nully-correct">// CORRECT</span><br />StringBuffer buf = ...;<br />takeString(new String(buf));<br /><span class="nully-comment nully-incorrect">// INCORRECT - getProperty may return null</span><br />String str = System.getProperty("someProp");<br />takeString(<span class="nully-error" title="Value passed to takeString() may be null">str</span>);<br />}</pre>
</li>
<li><strong>Local
variables.</strong> You cannot
assign a <code>null</code>
value to a <code>@NonNull</code>
variable. Any attempt to store a (possibly)
null value will produce a warning at edit- and compile-time, and will
throw an exception at runtime.
<pre class="nully-code">List someListMethod() { return ...; }<br /><br />void method() {<br /> <span class="nully-anno">@NonNull</span> List s;<br /> // CORRECT<br /> s = new ArrayList();<br /><br /> // CORRECT<br /> List other = new ArrayList();<br /> s = other;<br /><br /> // INCORRECT<br /> s = <span class="nully-error" title="Value assigned to s may be null">someListMethod()</span>;<br />}<br /></pre>
</li>
<li><strong>Method
return values. </strong>
When <code>@NonNull</code>
is specified for a method, it means any attempt to return a (possibly)
null value within that method will produce a warning at edit- and
compile-time, and will throw an exception at runtime. Values returned
from <code>@NonNull</code>
methods are guaranteed to be non-null due to generated run-time checks
in your code.
<pre class="nully-code"><span class="nully-anno">@NonNull</span> Object something() {<br /> <span class="nully-comment nully-correct">// CORRECT</span><br />return "Constant";<br /><span class="nully-comment nully-correct">// CORRECT</span><br />return new ArrayList();<br /><span class="nully-comment nully-incorrect">// INCORRECT - getProperty may return null</span><br />return <span class="nully-error" title="Returned value may be null">System.getProperty("someProp")</span>;<br /><br /> <span class="nully-comment nully-incorrect" title="Returned value may be null">// INCORRECT - value may be null</span><br />String value = null;<br />if (something) value = "hello";<br />return <span class="nully-error" title="Returned value may be null">value</span>;<br />}<br /><br />void somethingUser() {<br /> <span class="nully-comment nully-correct">// CORRECT - something() guaranteed not to return null</span><br /><span class="nully-anno">@NonNull</span> Object thing = something();<br />}</pre>
</li>
</ul>
<h4>Details</h4>
<p>Nully is implemented as a
plugin for the IntelliJ IDEA development
environment for Java. It cannot currently be used in any way outside
IDEA because of its heavy dependence on IDEA's Java source tree
framework.</p>
<h4>Status</h4>
<p>Nully is currently in development and is not available for public
release yet. You are free to check the project out of the CVS
repository to try it. A release is planned by the end of Summer 2005.</p>
<p>To use Nully annotations in
your project, you must include a small JAR
file in your application. This file will be released soon in the <a href="https://nully.dev.java.net/servlets/ProjectDocumentList?folderID=3225&expandFolder=3225&folderID=3225">Current
Release section</a> of this
project's file releases.</p>
</body>
</html>