Commit 7aafda96 authored by DanFabulich's avatar DanFabulich
Browse files

Fix code examples 

git-svn-id: https://sitemapgen4j.googlecode.com/svn/trunk@9 aa787bee-eda5-11dd-ada0-abde575de245
parent b17dc1fd

src/main/java/com/redfin/sitemapgenerator/package.html

+68 −62
Original line number Diff line number Diff line
@@ -2,7 +2,7 @@ 
<body>

<h1>How to use SitemapGen4j</h1>



SitemapGen4j is a tool to generate XML sitemaps in Java.

SitemapGen4j is a library to generate XML sitemaps in Java.



<h2>What's an XML sitemap?</h2>
@@ -18,88 +18,94 @@ Quoting from <a href="http://sitemaps.org/index.php">sitemaps.org</a>: 
<h2>Getting started</h2>



<p>The easiest way to get started is to just use the WebSitemapGenerator class, like this:

<blockquote><code>WebSitemapGenerator wsg = new WebSitemapGenerator("http://www.example.com", new File(".");<br>

wsg.addUrl("http://www.example.com/index.html"); // repeat multiple times<br>

wsg.write();</code></blockquote>



<pre name="code" class="java">WebSitemapGenerator wsg = new WebSitemapGenerator("http://www.example.com", myDir);

wsg.addUrl("http://www.example.com/index.html"); // repeat multiple times

wsg.write();</pre>



<h2>Configuring options</h2>



But there are a lot of nifty options available for URLs and for the generator as a whole.  To configure the generator, use a builder:

<blockquote><code>WebSitemapGenerator wsg = <b>WebSitemapGenerator.builder</b>("http://www.example.com", new File(".")<br>

&nbsp;&nbsp;<b>.gzip(true).build()</b>;<br>

wsg.addUrl("http://www.example.com/index.html"); // repeat multiple times<br>

wsg.write();</code></blockquote>



To configure the URLs, construct a real WebSitemapUrl with WebSitemapUrl.Options.

<blockquote><code>WebSitemapGenerator wsg = new WebSitemapGenerator("http://www.example.com", new File(".");<br>

WebSitemapUrl url = <b>WebSitemapUrl.Options</b>("http://www.example.com/index.html")<br>

&nbsp;&nbsp;<b>.lastMod(new Date()).priority(1.0).changeFreq(ChangeFreq.HOURLY).build()</b>;<br>

wsg.addUrl(url); // repeat multiple times<br>

wsg.write();</code></blockquote>



<h2>Configuring the date format</h2>



One important configuration option for the sitemap generator is the date format.  W3C allows you to use up to six

different date patterns in sitemaps; if you don't specify one, we'll try to guess which one you want, and we'll use

the default timezone of the local machine, which might not be what you prefer.

<pre name="code" class="java">WebSitemapGenerator wsg = WebSitemapGenerator.builder("http://www.example.com", myDir)

    .gzip(true).build(); // enable gzipped output

wsg.addUrl("http://www.example.com/index.html");

wsg.write();</pre>



<blockquote><code><b>W3CDateFormat dateFormat = new W3CDateFormat(Pattern.DAY);<br>

dateFormat.setTimeZone(TimeTimeZone.getTimeZone("GMT"));</b>

WebSitemapGenerator wsg = <b>WebSitemapGenerator.builder</b>("http://www.example.com", new File(".")<br>

&nbsp;&nbsp;<b>.dateFormat(dateFormat).build()</b>;<br>

wsg.addUrl("http://www.example.com/index.html"); // repeat multiple times<br>

wsg.write();</code></blockquote>

To configure the URLs, construct a WebSitemapUrl with WebSitemapUrl.Options.



<h2>Lots of URLs: a sitemap index file</h2>

<pre name="code" class="java">WebSitemapGenerator wsg = new WebSitemapGenerator("http://www.example.com", myDir);

WebSitemapUrl url = new WebSitemapUrl.Options("http://www.example.com/index.html")

    .lastMod(new Date()).priority(1.0).changeFreq(ChangeFreq.HOURLY).build();

// this will configure the URL with lastmod=now, priority=1.0, changefreq=hourly 

wsg.addUrl(url);

wsg.write();</pre>



One sitemap can contain a maximum of 50,000 URLs.  (Some sitemaps, like Google News sitemaps, can contain only 1,000 URLs.)

If you need to put more URLs than that in a sitemap, you'll have to use a sitemap index file.  Fortunately, 

WebSitemapGenerator can manage the whole thing for you.

<h2>Configuring the date format</h2>



<blockquote><code>WebSitemapGenerator wsg = new WebSitemapGenerator("http://www.example.com", new File(".");<br>

for (int i = 0; i < 100000; i++) wsg.addUrl("http://www.example.com/index"+i+".html");<br>

wsg.write();<br>

<b>wsg.writeSitemapsWithIndex();</b></code></blockquote>

One important configuration option for the sitemap generator is the date format.  The <a href="http://www.w3.org/TR/NOTE-datetime">W3C datetime standard</a> allows you to choose the precision of your datetime (anything from just specifying the year like "1997" to specifying the fraction of the second like "1997-07-16T19:20:30.45+01:00"); if you don't specify one, we'll try to guess which one you want, and we'll use the default timezone of the local machine, which might not be what you prefer.



<p>That will generate two sitemaps, sitemap1.xml and sitemap2.xml, and then generate a sitemap_index.xml file describing the two.</p>

<pre name="code" class="java">

// Use DAY pattern (2009-02-07), Greenwich Mean Time timezone

W3CDateFormat dateFormat = new W3CDateFormat(Pattern.DAY); 

dateFormat.setTimeZone(TimeZone.getTimeZone("GMT"));

WebSitemapGenerator wsg = WebSitemapGenerator.builder("http://www.example.com", myDir)

    .dateFormat(dateFormat).build(); // actually use the configured dateFormat

wsg.addUrl("http://www.example.com/index.html");

wsg.write();</pre>



<p>It's also possible to carefully organize your sub-sitemaps.  For example, it's recommended to group URLs with the same changeFreq together

(have one sitemap for changeFreq "daily" and another for changeFreq "yearly"), so you can modify the lastMod of the daily

sitemap without modifying the lastMod of the yearly sitemap.  To do that, just construct your sitemaps one at a time using 

the WebSitemapGenerator, then use the SitemapIndexGenerator to create a single index for all of them.</p>

<h2>Lots of URLs: a sitemap index file</h2>



<blockquote><code>SitemapIndexGenerator sig = new SitemapIndexGenerator("http://www.example.com", new File("sitemap_index.xml");<br>

for (int i = 0; i < 5; i++) sig.addUrl("http://www.example.com/sitemap"+i+".html", new Date(i));<br>

wsg.write();<br>

</code></blockquote>

One sitemap can contain a maximum of 50,000 URLs.  (Some sitemaps, like Google News sitemaps, can contain only 1,000 URLs.) If you need to put more URLs than that in a sitemap, you'll have to use a sitemap index file.  Fortunately,  WebSitemapGenerator can manage the whole thing for you. 



<pre name="code" class="java">WebSitemapGenerator wsg = new WebSitemapGenerator("http://www.example.com", myDir);

for (int i = 0; i &lt; 60000; i++) wsg.addUrl("http://www.example.com/doc"+i+".html");

wsg.write();

wsg.writeSitemapsWithIndex(); // generate the sitemap_index.xml

</pre>



<p>That will generate two sitemaps for 60K URLs: sitemap1.xml (with 50K urls) and sitemap2.xml (with the remaining 10K), and then generate a sitemap_index.xml file describing the two.</p>



<p>It's also possible to carefully organize your sub-sitemaps.  For example, it's recommended to group URLs with the same changeFreq together (have one sitemap for changeFreq "daily" and another for changeFreq "yearly"), so you can modify the lastMod of the daily sitemap without modifying the lastMod of the yearly sitemap.  To do that, just construct your sitemaps one at a time using  the WebSitemapGenerator, then use the SitemapIndexGenerator to create a single index for all of them.</p> 



<pre name="code" class="java">WebSitemapGenerator wsg;

// generate foo sitemap

wsg = WebSitemapGenerator.builder("http://www.example.com", myDir)

    .fileNamePrefix("foo").build();

for (int i = 0; i &lt; 5; i++) wsg.addUrl("http://www.example.com/foo"+i+".html");

wsg.write();

// generate bar sitemap

wsg = WebSitemapGenerator.builder("http://www.example.com", myDir)

    .fileNamePrefix("bar").build();

for (int i = 0; i &lt; 5; i++) wsg.addUrl("http://www.example.com/bar"+i+".html");

wsg.write();

// generate sitemap index for foo + bar 

SitemapIndexGenerator sig = new SitemapIndexGenerator("http://www.example.com", myFile);

sig.addUrl("http://www.example.com/foo.xml");

sig.addUrl("http://www.example.com/bar.xml");

sig.write();</pre>



<p>You could also use the SitemapIndexGenerator to incorporate sitemaps generated by other tools.  For example, you might use Google's official Python sitemap generator to generate some sitemaps, and use WebSitemapGenerator to generate some sitemaps, and use SitemapIndexGenerator to make an index of all of them.</p> 



<h2>Validate your sitemaps</h2>



SitemapGen4j can also validate your sitemaps.  (If you used SitemapGen4j to make the sitemaps, you shouldn't need to

do this unless there's a bug in our code.)  It's easy to configure the WebSitemapGenerator to automatically validate

your sitemaps right after you write them (but this does slow things down, naturally).

<p>SitemapGen4j can also validate your sitemaps using the official XML Schema Definition (XSD).  If you used SitemapGen4j to make the sitemaps, you shouldn't need to do this unless there's a bug in our code.  But you can use it to validate sitemaps generated by other tools, and it provides an extra level of safety.</p>



<blockquote><code>WebSitemapGenerator wsg = <b>WebSitemapGenerator.builder</b>("http://www.example.com", new File(".")<br>

&nbsp;&nbsp;<b>.autoValidate(true).build()</b>;<br>

wsg.addUrl("http://www.example.com/index.html"); // repeat multiple times<br>

wsg.write();</code></blockquote>

<p>It's easy to configure the WebSitemapGenerator to automatically validate your sitemaps right after you write them (but this does slow things down, naturally).</p> 



You can also use the SitemapValidator directly to manage sitemaps.  It has two methods: validateWebSitemap(File f)

and validateSitemapIndex(File f).

<pre name="code" class="java">WebSitemapGenerator wsg = WebSitemapGenerator.builder("http://www.example.com", myDir)

    .autoValidate(true).build(); // validate the sitemap after writing

wsg.addUrl("http://www.example.com/index.html");

wsg.write();</pre>



<h2>Google-specific sitemaps</h2>

<p>You can also use the SitemapValidator directly to manage sitemaps.  It has two methods: validateWebSitemap(File f) and validateSitemapIndex(File f).</p>



<p>Google can understand a wide variety of custom sitemap formats that they made up, including a Mobile sitemaps, Geo

sitemaps, Code sitemaps (for Google Code search), Google News sitemaps, and Video sitemaps.  SitemapGen4j can

generate any/all of these different types of sitemaps.</p>

<h2>Google-specific sitemaps</h2>



<p>To generate a special type of sitemap, just use GoogleMobileSitemapGenerator, GoogleGeoSitemapGenerator,

GoogleCodeSitemapGenerator, GoogleCodeSitemapGenerator, GoogleNewsSitemapGenerator, or GoogleVideoSitemapGenerator

instead of WebSitemapGenerator.</p>

<p>Google can understand a wide variety of custom sitemap formats that they made up, including a Mobile sitemaps, Geo sitemaps, Code sitemaps (for Google Code search), Google News sitemaps, and Video sitemaps.  SitemapGen4j can generate any/all of these different types of sitemaps.</p>



<p>You can't mix-and-match regular URLs with Google-specific sitemaps, so you'll also have to use a

GoogleMobileSitemapUrl, GoogleGeoSitemapUrl, GoogleCodeSitemapUrl, GoogleNewsSitemapUrl, or GoogleVideoSitemapUrl

instead of a WebSitemapUrl.  Each of them has unique configurable options not available to regular web URLs.</p> 

<p>To generate a special type of sitemap, just use GoogleMobileSitemapGenerator, GoogleGeoSitemapGenerator, GoogleCodeSitemapGenerator, GoogleCodeSitemapGenerator, GoogleNewsSitemapGenerator, or GoogleVideoSitemapGenerator instead of WebSitemapGenerator.</p>



<p>You can't mix-and-match regular URLs with Google-specific sitemaps, so you'll also have to use a GoogleMobileSitemapUrl, GoogleGeoSitemapUrl, GoogleCodeSitemapUrl, GoogleNewsSitemapUrl, or GoogleVideoSitemapUrl instead of a WebSitemapUrl.  Each of them has unique configurable options not available to regular web URLs.</p>  

</body>

</html>
 
 No newline at end of file

src/test/java/com/redfin/sitemapgenerator/TutorialExampleTest.java

0 → 100644
+89 −0
Original line number Diff line number Diff line 
package com.redfin.sitemapgenerator;



import java.io.File;

import java.util.Date;

import java.util.TimeZone;



import junit.framework.TestCase;



import com.redfin.sitemapgenerator.W3CDateFormat.Pattern;



public class TutorialExampleTest extends TestCase {

	

	File myDir;

	File myFile;

	

	public void setUp() throws Exception {

		myDir = File.createTempFile(TutorialExampleTest.class.getSimpleName(), "");

		myDir.delete();

		myDir.mkdir();

		myDir.deleteOnExit();

		myFile = new File(myDir, "sitemap_index.xml");

	}

	

	public void tearDown() {

		for (File file : myDir.listFiles()) {

			file.deleteOnExit();

			file.delete();

		}

		myDir.delete();

		myDir = null;

	}

	

	public void testGettingStarted() throws Exception {

		WebSitemapGenerator wsg = new WebSitemapGenerator("http://www.example.com", myDir);

		wsg.addUrl("http://www.example.com/index.html"); // repeat multiple times

		wsg.write();

	}



	public void testConfiguringWsgOptions() throws Exception {

		WebSitemapGenerator wsg = WebSitemapGenerator.builder("http://www.example.com", myDir)

			.gzip(true).build(); // enable gzipped output

		wsg.addUrl("http://www.example.com/index.html");

		wsg.write();

	}

	public void testConfiguringUrlOptions() throws Exception {

		WebSitemapGenerator wsg = new WebSitemapGenerator("http://www.example.com", myDir);

		WebSitemapUrl url = new WebSitemapUrl.Options("http://www.example.com/index.html")

			.lastMod(new Date()).priority(1.0).changeFreq(ChangeFreq.HOURLY).build();

		// this will configure the URL with lastmod=now, priority=1.0, changefreq=hourly 

		wsg.addUrl(url);

		wsg.write();

	}

	public void testConfiguringDateFormat() throws Exception {

		W3CDateFormat dateFormat = new W3CDateFormat(Pattern.DAY); // e.g. 2008-01-29

		dateFormat.setTimeZone(TimeZone.getTimeZone("GMT")); // Use Greenwich Mean Time timezone

		WebSitemapGenerator wsg = WebSitemapGenerator.builder("http://www.example.com", myDir)

			.dateFormat(dateFormat).build(); // actually use the configured dateFormat

		wsg.addUrl("http://www.example.com/index.html");

		wsg.write();

	}

	public void testLotsOfUrlsWsg() throws Exception {

		WebSitemapGenerator wsg = new WebSitemapGenerator("http://www.example.com", myDir);

		for (int i = 0; i < 60000; i++) wsg.addUrl("http://www.example.com/index.html");

		wsg.write();

		wsg.writeSitemapsWithIndex(); // generate the sitemap_index.xml

	}

	public void testLotsOfUrlsSig() throws Exception {

		WebSitemapGenerator wsg;

		// generate foo sitemap

		wsg = WebSitemapGenerator.builder("http://www.example.com", myDir).fileNamePrefix("foo").build();

		for (int i = 0; i < 5; i++) wsg.addUrl("http://www.example.com/foo"+i+".html");

		wsg.write();

		// generate bar sitemap

		wsg = WebSitemapGenerator.builder("http://www.example.com", myDir).fileNamePrefix("bar").build();

		for (int i = 0; i < 5; i++) wsg.addUrl("http://www.example.com/bar"+i+".html");

		wsg.write();

		// generate sitemap index for foo + bar 

		SitemapIndexGenerator sig = new SitemapIndexGenerator("http://www.example.com", myFile);

		sig.addUrl("http://www.example.com/foo.html");

		sig.addUrl("http://www.example.com/bar.html");

		sig.write();

	}

	public void testAutoValidate() throws Exception {

		WebSitemapGenerator wsg = WebSitemapGenerator.builder("http://www.example.com", myDir)

			.autoValidate(true).build(); // validate the sitemap after writing

		wsg.addUrl("http://www.example.com/index.html");

		wsg.write();

	} 

}