'. '

Sources

From APIDesign

(Difference between revisions)
Jump to: navigation, search
(Download)
Current revision (20:50, 30 October 2014) (edit) (undo)
(Usage)
 
(18 intermediate revisions not shown.)
Line 1: Line 1:
 +
All the code snippets shown in the [[TheAPIBook|Practical API Design]] book
 +
are extracted from real projects. As such it is guaranteed they are correct, they compile and can even be executed, [[debugger|debugged]] and tested.
 +
 +
Moreover, it is often not enough to see just a few lines of code in middle of a page, readers are recommended to get the whole tree of [[sources]], including their history and play with them for real. Preferably use [[Mercurial]] to clone the [[sources]] [[Hg]] [http://source.apidesign.org/hg/apidesign/ repository]:
 +
 +
<source lang="bash">
 +
$ hg clone http://source.apidesign.org/hg/apidesign/
 +
</source>
 +
=== Environment ===
=== Environment ===
-
In order to use the sample sources you need:
+
In order to use the sample [[sources]] you may need:
-
* JDK 1.6.0 - necessary for compilation and execution
+
* At least [[JDK]]7 or [[JDK]8 - necessary for compilation and execution
-
* Ant 1.7.0 - allows simple compilation and execution from command line
+
* At least [[Ant]] 1.8.1 - allows simple compilation and execution from command line
-
* NetBeans IDE 6.0 - all projects are configured to smoothly open in NetBeans IDE
+
* At least [[NetBeans]] IDE 6.9 - all projects are configured to smoothly open in [[NetBeans]] IDE
 +
 
 +
If you managed to successfully start [[NetBeans]] IDE, you probably have everything necessary installed on your computer.
=== Download ===
=== Download ===
-
The sources for sample examples are processed, verified and published daily on API Design [http://hudson.apidesign.org/job/samples continuous build server]. Downloaded the latest version of apidesign-XYZ.zip, unzip it on your local computer. Start NetBeans IDE and open individual projects as needed.
+
Those that prefer [[ZIP]] over [[Mercurial]] (for example to get also all necessary libraries with the [[sources]]) can download the latest published build from our
 +
[http://hudson.apidesign.org/job/samples continuous build server]. Download the latest version of apidesign.zip, unzip it on your local computer. Start [[NetBeans]] IDE and open individual projects as needed.
=== Usage ===
=== Usage ===
-
You need to run <tt>build.xml</tt> before opening the projects in the IDE. Otherwise the projects have unsolvable broken references.
+
It is always better to build the root project:
 +
<source lang="bash">
 +
$ cd samples # in case of [[Mercurial]] checkout
 +
$ ant build.xml # or from the IDE
 +
</source>
 +
before opening its sub-projects in the IDE. Failing to do so may cause the projects to show ''broken references'' (due to missing [[libraries]] that need to be downloaded first in the [[Mercurial]] case). Btw. in case you need to perform really clean build and download all [[libraries]] once again, you can
 +
<source lang="bash">
 +
$ cd samples # in case of [[Mercurial]] checkout
 +
$ rm -r libs/dist
 +
</source>
 +
 
 +
=== Funny Stories ===
 +
 
 +
My [[Hudson]] server crashed in early months of 2014. I had to configure it from scratch. While doing so, I forgot to configure the job to produce ''apidesign.zip'' file with [[sources]]. Has anyone noticed? Nobody sent me an email! Just yesterday Jáchym, my co-worker, who I torture by forcing him to read [[TheAPIBook]] and become [[good]] [[API]] designer, stopped in my office and timidly asked: ''Where can I get the sources? There is no [[ZIP]] file!''
 +
 
 +
For a while I tried to blame him for not using [[Mercurial]], but after a while I realized the problem is on my side. As a result, the [http://hudson.apidesign.org/job/samples/ zip file with sources] is back as of Aug 8, 2014. Will anyone use them? It would be nice as reading [[TheAPIBook|Practical API Design]] book without having whole [[sources]] at your hand is like trying to understand [[Swing]] just by reading its [[Javadoc]].
 +
 
 +
Let me know (Jáchym, you have to) whether you found the [[sources]] useful.
-
The build fails on JDK 1.5 because of <tt>ServiceLoader</tt> usages. This needs to be mentioned somewhere, and <tt>build.xml</tt> should perhaps skip that example when building on 1.5.
+
<comments/>

Current revision

All the code snippets shown in the Practical API Design book are extracted from real projects. As such it is guaranteed they are correct, they compile and can even be executed, debugged and tested.

Moreover, it is often not enough to see just a few lines of code in middle of a page, readers are recommended to get the whole tree of sources, including their history and play with them for real. Preferably use Mercurial to clone the sources Hg repository:

$ hg clone http://source.apidesign.org/hg/apidesign/

Contents

Environment

In order to use the sample sources you may need:

  • At least JDK7 or [[JDK]8 - necessary for compilation and execution
  • At least Ant 1.8.1 - allows simple compilation and execution from command line
  • At least NetBeans IDE 6.9 - all projects are configured to smoothly open in NetBeans IDE

If you managed to successfully start NetBeans IDE, you probably have everything necessary installed on your computer.

Download

Those that prefer ZIP over Mercurial (for example to get also all necessary libraries with the sources) can download the latest published build from our continuous build server. Download the latest version of apidesign.zip, unzip it on your local computer. Start NetBeans IDE and open individual projects as needed.

Usage

It is always better to build the root project:

$ cd samples # in case of [[Mercurial]] checkout
$ ant build.xml # or from the IDE

before opening its sub-projects in the IDE. Failing to do so may cause the projects to show broken references (due to missing libraries that need to be downloaded first in the Mercurial case). Btw. in case you need to perform really clean build and download all libraries once again, you can

$ cd samples # in case of [[Mercurial]] checkout
$ rm -r libs/dist

Funny Stories

My Hudson server crashed in early months of 2014. I had to configure it from scratch. While doing so, I forgot to configure the job to produce apidesign.zip file with sources. Has anyone noticed? Nobody sent me an email! Just yesterday Jáchym, my co-worker, who I torture by forcing him to read TheAPIBook and become good API designer, stopped in my office and timidly asked: Where can I get the sources? There is no ZIP file!

For a while I tried to blame him for not using Mercurial, but after a while I realized the problem is on my side. As a result, the zip file with sources is back as of Aug 8, 2014. Will anyone use them? It would be nice as reading Practical API Design book without having whole sources at your hand is like trying to understand Swing just by reading its Javadoc.

Let me know (Jáchym, you have to) whether you found the sources useful.

<comments/>

Personal tools
buy