com.hp.autonomy.aci.content.identifier.reference.ReferencesBuilder Maven / Gradle / Ivy
Show all versions of content-parameter-api Show documentation
/*
* Copyright 2009-2015 Hewlett-Packard Development Company, L.P.
* Licensed under the MIT License (the "License"); you may not use this file except in compliance with the License.
*/
package com.hp.autonomy.aci.content.identifier.reference;
import org.apache.commons.lang.Validate;
import java.util.Arrays;
import java.util.Collections;
import java.util.Iterator;
import java.util.LinkedHashSet;
import java.util.Set;
/**
* A builder class for aggregating multiple references into a single object.
*
* This class makes no attempt at internal synchronization and is not safe to be used by multiple threads without
* external synchronization.
*/
public class ReferencesBuilder extends AbstractReferences {
private final Set references = new LinkedHashSet();
/**
* Creates an empty {@code ReferencesBuilder}.
*/
// Only required because we have 2 var args constructors, causing ambiguity
public ReferencesBuilder() {
}
/**
* Creates a {@code ReferencesBuilder} with the specified reference and section number as the only entry.
*
* @param reference The initial ids
* @param section The section number
*/
public ReferencesBuilder(final String reference, final int section) {
doAppend(Collections.singletonList(new Reference(reference, section)));
}
/**
* Creates a {@code ReferencesBuilder} with the specified references.
*
* @param references The initial references
*/
public ReferencesBuilder(final String... references) {
doAppend(Arrays.asList(references));
}
/**
* Creates a {@code ReferencesBuilder} with the specified references. The {@link Iterable} can contain instances of
* {@link String} or {@link Reference}. Note that all instances of {@link References} are suitable iterables.
*
* @param references The initial references
*/
public ReferencesBuilder(final Iterable... references) {
doAppend(references);
}
/**
* Appends the specified reference and section number to this instance, returning {@code this}.
*
* @param reference The reference to append
* @param section The section number of the reference to append
* @return {@code this}
*/
@Override
public ReferencesBuilder append(final String reference, final int section) {
return doAppend(Collections.singletonList(new Reference(reference, section)));
}
/**
* Appends the specified references to this instance, returning {@code this}.
*
* @param references The references to append
* @return {@code this}
*/
@Override
public ReferencesBuilder append(final String... references) {
return doAppend(Arrays.asList(references));
}
/**
* Appends the specified references to this instance, returning {@code this}.
*
* @param references The references to append
* @return {@code this}
*/
@Override
public ReferencesBuilder append(final Iterable... references) {
return doAppend(references);
}
private ReferencesBuilder doAppend(final Iterable... references) {
Validate.notNull(references, "The iterable provided was null");
// In case of nulls, build a new Set and then add them all
final Set newReferences = new LinkedHashSet();
for(final Iterable referenceIterable : references) {
Validate.notNull(referenceIterable, "One of the iterables provided was null");
for(final Object reference : referenceIterable) {
Validate.notNull(reference, "One of the references provided was null");
if(reference instanceof Reference) {
newReferences.add((Reference)reference);
}
else if (reference instanceof String) {
newReferences.add(new Reference((String)reference));
}
else {
throw new IllegalArgumentException("One of the references was of an unknown class: " + reference.getClass().getName());
}
}
}
this.references.addAll(newReferences);
return this;
}
@Override
public Iterator iterator() {
// We may later decide to make ReferencesBuilder a full Collection but for now we need to avoid allowing removal
// via Iterator, so wrap our collection
return Collections.unmodifiableCollection(references).iterator();
}
/**
* Whether or not the {@code ReferencesBuilder} is empty.
*
* @return {@code true} if and only if the size is 0.
*/
@Override
public boolean isEmpty() {
return references.isEmpty();
}
/**
* The number of references in the builder.
*
* @return The size of the builder
*/
@Override
public int size() {
return references.size();
}
/**
* Converts an iterable of references into a {@code ReferencesBuilder}. This method can be more efficient than using
* the equivalent constructor but the returned object might be backed by the object provided.
*
* @param references The references to convert
* @return An equivalent instance of {@code ReferencesBuilder}
*/
public static ReferencesBuilder from(final Iterable references) {
return (references instanceof ReferencesBuilder) ? (ReferencesBuilder)references : new ReferencesBuilder(references);
}
}