galimatias

A URL parsing and normalization library written in Java.

Fork me on GitHub

galimatias

Build Status Coverage Status

galimatias is a URL parsing and normalization library written in Java.

Design goals

Gotchas

galimatias is not a generic URI parser. It can parse any URI, but only schemes defined in the URL Standard (i.e. http, https, ftp, ws, wss, gopher, file) will be parsed as hierarchical URIs. For example, in git://github.com/smola/galimatias.git you'll be able to extract scheme (i.e. git) and scheme data (i.e. //github.com/smola/galimatias.git), but not host (i.e. github.com). This is intended. We cannot guarantee that applying a set of generic rules won't break certain kind of URIs, so we do not try with them. I will consider adding further support for other schemes if enough people provides solid use cases and testing. You can check this issue if you are interested.

But, why?

galimatias started out of frustration with java.net.URL and java.net.URI. Both of them are good for basic use cases, but severely broken for others:

Setup with Maven

galimatias is available at Maven Central. Just add to your pom.xml <dependencies> section:

<dependency>
  <groupId>io.mola.galimatias</groupId>
  <artifactId>galimatias</artifactId>
  <version>0.2.0</version>
</dependency>

Development snapshots are also available at Sonatype OSS Snapshots repository.

Getting started

Parse a URL

// Parse
String urlString = //...
URL url;
try {
  url = URL.parse(urlString);
} catch (GalimatiasParseException ex) {
  // Do something with non-recoverable parsing error
}

Convert to java.net.URL

URL url = //...
java.net.URL javaURL;
try {
  javaURL = url.toJavaURL();
} catch (MalformedURLException ex) {
  // This can happen if scheme is not http, https, ftp, file or jar.
}

Convert to java.net.URI

URL url = //...
java.net.URI javaURI;
try {
  javaURI = url.toJavaURI();
} catch (URISyntaxException ex) {
  // This will happen in rare cases such as "foo://"
}

Parse a URL with strict error handling

You can use a strict error handler that will throw an exception on any invalid URL, even if it's a recovarable error.

URLParsingSettings settings = URLParsingSettings.create()
  .withErrorHandler(StrictErrorHandler.getInstance());
URL url = URL.parse(settings, urlString);

Documentation

Check out the Javadoc.

Contribute

Did you find a bug? Report it on GitHub.

Did you write a patch? Send a pull request.

Something else? Email me at santi@mola.io.

License

Copyright (c) 2013-2014 Santiago M. Mola santi@mola.io

galimatias is released under the terms of the MIT License.