com.hp.autonomy.aci.content.identifier.reference.Reference Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of content-parameter-api Show documentation
API for representing aspects of IDOL's Content server, including FieldText and document References
The newest version!
/*
 * Copyright 2009-2015 Open Text.
 *
 * Licensed under the MIT License (the "License"); you may not use this file
 * except in compliance with the License.
 *
 * The only warranties for products and services of Open Text and its affiliates
 * and licensors ("Open Text") are as may be set forth in the express warranty
 * statements accompanying such products and services. Nothing herein should be
 * construed as constituting an additional warranty. Open Text shall not be
 * liable for technical or editorial errors or omissions contained herein. The
 * information contained herein is subject to change without notice.
 */

package com.hp.autonomy.aci.content.identifier.reference;

import com.autonomy.aci.client.util.AciURLCodec;
import org.apache.commons.lang.StringUtils;
import org.apache.commons.lang.Validate;

import java.util.Collections;
import java.util.Iterator;

/**
 * A representation of a document reference. A document reference is a string, and optionally a section number, that
 * identifies a document within IDOL's Content server. Though references allow for complex many-to-many relationships
 * with documents, they are usually one-to-one or one-to-many by convention.
 */
public class Reference extends AbstractReferences {
    private final String reference;
    private final int section;

    /**
     * Creates a new {@code Reference} instance for the specified string reference.
     *
     * @param reference The document reference
     */
    public Reference(final String reference) {
        Validate.isTrue(StringUtils.isNotBlank(reference), "Reference must not be blank");

        this.reference = reference;

        section = -1;
    }

    /**
     * Creates a new {@code Reference} instance for the specified string reference and section number.
     *
     * @param reference The document reference
     * @param section The section number
     */
    public Reference(final String reference, final int section) {
        Validate.isTrue(StringUtils.isNotBlank(reference), "Reference must not be blank");
        Validate.isTrue(section >= 0, "Section number must not be less than zero");

        this.reference = reference;
        this.section = section;
    }

    @Override
    public Iterator iterator() {
        // Should probably rewrite this to use a custom iterator
        return Collections.singletonList(this).iterator();
    }

    /**
     * Accessor for the string reference of the document reference, i.e. the unescaped reference without the section
     * number.
     *
     * @return The document reference
     */
    public String getReference() {
        return reference;
    }

    /**
     * Whether or not this reference has a section number.
     *
     * @return {@code true} if and only if the reference has a section number.
     */
    public boolean hasSection() {
        return section != -1;
    }

    /**
     * Accessor for the section number, if the reference has a section number.
     *
     * @return The section number
     * @throws IllegalStateException if the reference doesn't have a section number
     */
    public int getSection() {
        if (!hasSection()) {
            throw new IllegalStateException("Reference does not have a section number");
        }

        return section;
    }

    /**
     * For a single reference the size is always 1.
     *
     * @return {@code 1}
     */
    @Override
    public int size() {
        return 1;
    }

    /**
     * A single reference can never be empty.
     *
     * @return {@code false}
     */
    @Override
    public boolean isEmpty() {
        return false;
    }

    /**
     * The string representation of this identifier, suitable for use as part of a DREREPLACE.
     *
     * Sectioning does not apply for index commands so the section number is discarded.
     *
     * @return A suitably encoded string for use with index commands
     */
    @Override
    public String toIndexingString() {
        return AciURLCodec.getInstance().encode(reference);
    }

    @Override
    public String toString() {
        final StringBuilder builder = new StringBuilder(AciURLCodec.getInstance().encode(reference));

        if (hasSection()) {
            builder.append('$').append(section);
        }

        return builder.toString();
    }
}