First rule: make it easy

One of the problems I have with many Java libraries is that they don’t cater to the common usage. Take working with zip archives. Most of the time all you want to do is unpack it to a directory, preserving the directory structure instead of flattening them out. So you’d expect to find something in the java.util.zip API like:
unpack( File zipFile, File destinationDir )

I'm sorry, no such luck. Sure, it's very easy to write, but that's not the point. If you're creating a library, why not make it a one-liner for the most common actions? Compare this with the Archive::Zip module from CPAN:

my $zip_file = get_filename_from_somewhere( ... );
my $zip = Archive::Zip->new( $zip_file );
if ( $zip ) {
    $zip->extractTree( '/path/to/unpack' );
}
else {
    die "Read of $zip_file failed\n";
}

And here's what I have to do in Java, and this is even using a separate utility method for coping a stream to a file:

public static Collection unpackZip( File file, File destDir )
    throws IOException
{
    if ( ! file.isFile() )
    {
        throw new IllegalArgumentException(
                "File '" + file + "' not a valid file" );
    }
    List unzipped = new ArrayList();
    ZipFile zip = new ZipFile( file, ZipFile.OPEN_READ );
    for ( Enumeration enum = zip.entries(); enum.hasMoreElements(); )
    {
        ZipEntry entry = (ZipEntry)enum.nextElement();
        String name = entry.getName();
        File destFile = new File( destDir, name );
        File destParent = destFile.getParentFile();
        if ( ! destParent.isDirectory() )
        {
            if ( ! destParent.mkdirs() )
            {
                throw new IOException( "Cannot create directory '" + destParent + "'" );
            }
        }
        InputStream zipIn = zip.getInputStream( entry );
        copy( zipIn, destFile );
        zipIn.close();
        unzipped.add( destFile );
    }
    return unzipped;
}

Creating a zip file follows a similar pattern. Dumb dumb dumb.