use more neutral sample in javadoc
Add Metadata.updates(metadata) method

This makes a useful piece of logic previously part of the repository impl usable by a broader audience.