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    
013    package com.ibm.rational.wvcm.stp.cq;
014    
015    import javax.wvcm.WvcmException;
016    
017    import 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     */
027    public 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    }