001/*
002 * file CqHistoryFieldValue.java
003 * Licensed Materials - Property of IBM
004 * Restricted Materials of IBM 
005 *
006 * com.ibm.rational.wvcm.stp.cq.CqHistoryFieldValue
007 *
008 * (C) Copyright IBM Corporation 2006, 2008.  All Rights Reserved.
009 * Note to U.S. Government Users Restricted Rights:  Use, duplication or 
010 * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp.
011 */
012
013package com.ibm.rational.wvcm.stp.cq;
014
015import javax.wvcm.WvcmException;
016
017import com.ibm.rational.wvcm.stpex.StpExBase;
018
019/**
020 * An extension of the CqFieldValue StpProperty interface representing the value
021 * of a ClearQuest record history field. The VALUE of this property is an array
022 * of strings, each representing a single event in the lifetime of the record.
023 * Each event has several sub-fields indicating the time of the event, the user
024 * that caused the event, initial and final states, etc. The sub-fields are
025 * separated by "\t" characters.
026 */
027public interface CqHistoryFieldValue extends CqFieldValue<String[]>
028{
029    /**
030     * An array of labels for the sub-fields of an event in the VALUE
031     * array.
032     */
033    MetaPropertyName<String[]> DISPLAY_NAME_HEADER =
034        new MetaPropertyName<String[]>(StpExBase.METADATA_NAMESPACE,
035                                       "display-name-header");
036
037    /**
038     * Returns the value of the {@link #DISPLAY_NAME_HEADER DISPLAY_NAME_HEADER}
039     * property as defined by this proxy.
040     * 
041     * @return A String[], each element of which contains a label for one
042     *         sub-field of a history event. The length of this array defines
043     *         the number of sub-fields in each String of the VALUE array.
044     * 
045     * @throws WvcmException if this proxy does not define a value for the
046     *             {@link #DISPLAY_NAME_HEADER DISPLAY_NAME_HEADER} property.
047     */
048    public String[] getDisplayNameHeader() throws WvcmException;
049
050    /**
051     * An array of labels for the sub-fields of an event in the
052     * {@link #HISTORIES_FOR_EXPORT} array.
053     */
054    MetaPropertyName<String[]> DISPLAY_NAME_HEADER_FOR_EXPORT =
055        new MetaPropertyName<String[]>(StpExBase.METADATA_NAMESPACE,
056                                       "display-name-header-for-export");
057
058    /**
059     * Returns the value of the
060     * {@link #DISPLAY_NAME_HEADER_FOR_EXPORT DISPLAY_NAME_HEADER_FOR_EXPORT}
061     * property as defined by this proxy.
062     * 
063     * @return A String[], each element of which contains a label for one
064     *         sub-field of a history event in the {@link #HISTORIES_FOR_EXPORT}
065     *         array. The length of this array defines the number of sub-fields
066     *         in each String of the {@link #HISTORIES_FOR_EXPORT} array.
067     * 
068     * @throws WvcmException if this proxy does not define a value for the
069     *             {@link #DISPLAY_NAME_HEADER_FOR_EXPORT DISPLAY_NAME_HEADER_FOR_EXPORT}
070     *             property.
071     */
072    public String[] getDisplayNameHeaderForExport() throws WvcmException;
073
074    /**
075     * An array of the history events in a format suitable for export
076     */
077    MetaPropertyName<String[]> HISTORIES_FOR_EXPORT =
078        new MetaPropertyName<String[]>(StpExBase.METADATA_NAMESPACE,
079                                       "histories-for-export");
080
081    /**
082     * Returns the value of the
083     * {@link #HISTORIES_FOR_EXPORT HISTORIES_FOR_EXPORT} property as defined by
084     * this proxy.
085     * 
086     * @return A String[], each element of which describes an event in the
087     *         history of this field's record. Each event String contains
088     *         sub-fields appropriate for export of the the event information.
089     * 
090     * @throws WvcmException if this proxy does not define a value for the
091     *             {@link #HISTORIES_FOR_EXPORT HISTORIES_FOR_EXPORT} property.
092     */
093    public String[] getHistoriesForExport() throws WvcmException;
094}