Package mks.ci.server.engine

Class LocalTriggerManager.ScriptFieldBean

  • All Implemented Interfaces:
    mks.frame.triggers.ScriptExposableBean
    Enclosing class:
    LocalTriggerManager
    public static class LocalTriggerManager.ScriptFieldBean
extends LocalTriggerManager.ScriptAdminBean
implements mks.frame.triggers.ScriptExposableBean
    A bean describing a single field. These beans are obtained via the imServerBean, via the .getFieldBean() method. For example, 
     bsf.lookupBean("imServerBean").getFieldBean("Priority");
    This bean is primarily useful to determine the type of a field, and valid values, for example, the ordered list of valid values in a pick field.

    • Constructor Detail

      • ScriptFieldBean

        public ScriptFieldBean​(mks.ci.server.engine.Field f,
                       int userId,
                       java.sql.Connection c)

      • ScriptFieldBean

        public ScriptFieldBean​(mks.ci.server.engine.Field f,
                       mks.ci.common.AdminLookup al)

    • Method Detail

      • toString

        public java.lang.String toString()
        Returns a summary of this object.
        Overrides:
        toString in class java.lang.Object

      • getMaxValue

        public java.lang.Object getMaxValue()
        If getFieldType() is the value "int" or ``float'', then this method will return the maximum integer/float value which it allows.
        Returns:
        a java ``Double'' or ``Integer'' object.

      • getMinValue

        public java.lang.Object getMinValue()
        If getFieldType() is the value "int" or ``float'', then this method will return the minimum integer/float value which it allows.
        Returns:
        a java ``Double'' or ``Integer'' object.

      • getPickFieldValues

        public java.lang.String[] getPickFieldValues()
        If getFieldType() is the value "pick", then this method will return all the valid values for this field. These are ordered in the pick field ordering.
        Returns:
        an array of strings, in order, being all the string values that the pick field is allowed to take.

      • getPickFieldActiveValueList

        public java.util.List<java.lang.String> getPickFieldActiveValueList()
        If getFieldType() is the value "pick", then this method will return the "active" values for this field ordered in the pick field ordering. A caller can then use .contains() method on the returned list to determine if the desired value is a valid and active pick for the field.
        Returns:
        a List of strings, in order, of the values that are active for the pick field

      • getPickFieldMappings

        public java.util.Map<java.lang.String,​java.lang.Integer> getPickFieldMappings()
        If getFieldType() is the value "pick", then this method will return a mapping of the display strings to the underlying numeric pick values. Use the .get(displayString) method to obtain the actual value. 
         var priorityFieldBean = serverBean.getFieldBean("Priority")
 var priorityMap = priorityFieldBean.getPickFieldMappings();
 var currentPriority = deltaBean.getFieldValue("Priority");
 var currentPriorityInt = priorityMap.get(currentPriority);
        If the string passed to get does not exist in the map (i.e. in the picklist), then null will be returned.
        Returns:
        an Map<String, Integer> the keys being all the string display values for the pick field, with their associated values being their integer values.

      • isFVA

        public boolean isFVA()
        Is this field a Field Value Attribute? Note that this cannot be returned in the field type: the field type is that which emulates the field which we are backing. For example, if you have a FVA which is backed by R1.State (thru the relationship field named R1, access to the State field on the related issue), then the field type is "pick".

      • getFVARelationship

        public java.lang.String getFVARelationship()
                                    throws mks.frame.triggers.TriggerException
        If this field is an FVA field (i.e. isFVA() returns true), then get the name of the relationship field thru which we find the issue that we wish to obtain the field attribute from. For example, if you have an FVA which is backed by R1.State (thru the relationship field named R1, access to the State field on the related issue), then this returns the fieldname "R1".
        Throws:
        mks.frame.triggers.TriggerException - if this field is not an FVA field.

      • getFVAField

        public java.lang.String getFVAField()
                             throws mks.frame.triggers.TriggerException
        If this field is an FVA field (i.e. isFVA() returns true), then get the name of the target field on the issue that we find thru the relationship field. For example, if you have an FVA which is backed by R1.State (thru the relationship field named R1, access to the State field on the related issue), then this returns the fieldname "State".
        Throws:
        mks.frame.triggers.TriggerException - if this field is not an FVA field.

      • isForwardRelationship

        public boolean isForwardRelationship()
                              throws mks.frame.triggers.TriggerException
        Returns true if this field is a bidirectional relationship and is in the "forward" direction.
        Returns:
        true if this is a forward relationship, false if not a bidirectional relationship or a reverse relationship.
        Throws:
        mks.frame.triggers.TriggerException

      • getBackingType

        public java.lang.String getBackingType()
                                throws mks.frame.triggers.TriggerException
        If this field is an issue backed picklist (i.e. getFieldType() returns the string ibpl), then get the name of the type which backs the picklist.
        Throws:
        mks.frame.triggers.TriggerException - if this field is not an ibpl.

      • getBackingTextField

        @Deprecated
public java.lang.String getBackingTextField()
                                     throws mks.frame.triggers.TriggerException
        Deprecated.
        If this field is an issue backed picklist (i.e. getFieldType() returns the string ibpl), then get the name of the text field on the backing type which is used for the display of each item in the picklist.
        As of the 2009 release, the use of backing text fields are deprecated, and only maintained for backwards compatability purposes. New IBPL fields are created with a text format string; and the GUI admin can no longer set the backing text field. In this case, the return value is null.
        Throws:
        mks.frame.triggers.TriggerException - if this field is not an ibpl.
        See Also:
        getBackingTextFormat()

      • getBackingTextFormat

        public java.lang.String getBackingTextFormat()
                                      throws mks.frame.triggers.TriggerException
        If this field is an issue backed picklist (i.e. getFieldType() returns the string ibpl), then get the text format string used to display each item in the generated picklist. The format string has field names in braces within it, for example: 
        {ID}: {Type}: Summary: {Summary}
        Throws:
        mks.frame.triggers.TriggerException - if this field is not an ibpl.

      • getBackingStates

        public java.lang.String getBackingStates()
                                  throws mks.frame.triggers.TriggerException
        If this field is an issue backed picklist (i.e. getFieldType() returns the string ibpl), then get the list of names of the states that the backing type must be in to be a member of the picklist.
        Returns:
        a comma-delimited list of state names. null indicates any state.
        Throws:
        mks.frame.triggers.TriggerException - if this field is not an ibpl.

      • getQBRQuery

        public java.lang.String getQBRQuery()
                             throws mks.frame.triggers.TriggerException
        If this field is a query backed relationship (i.e. getFieldType() returns the string qbr), then get the name of the query which is used to populate the relationship values.
        Returns:
        the query name.
        Throws:
        mks.frame.triggers.TriggerException - if this field is not a qbr.

      • getQBRQueryCorrelations

        public java.lang.String getQBRQueryCorrelations()
                                         throws mks.frame.triggers.TriggerException
        If this field is a query backed relationship (i.e. getFieldType() returns the string qbr), then get the list of the fields to correlate between the issue and the query.
        Returns:
        a comma-delimited list of correlations; each such entry is a pair of field names, being the source and target field names.
        Throws:
        mks.frame.triggers.TriggerException - if this field is not a qbr.

      • getFieldType

        public java.lang.String getFieldType()
        Return the type of this field in a string form.
        Returns:
        A String representing the type of the fields. Possible returned strings are:
        • user
        • group
        • project
        • state
        • int
        • pick
        • boolean
        • float
        • date
        • shorttext
        • loggingtext
        • longtext
        • relationship
        • attachment
        • siproject
        • range
        • phase
        • qbr
        • ibpl
        • sourcelink
        • customfielddefinition
        • customfieldvalue
        Note: For an FVA, you must test using the isFVA() method; this method will return the type of the field being backed by the FVA. Some of the types that can be backed by an FVA are actually exposed as picklists: Project and State fields when FVA'ed will return "pick".

      • isRichContent

        public boolean isRichContent()
        Is this a longtext field with the rich content attribute?
        Returns:
        true if this is a rich content field.

      • isLoggingText

        public boolean isLoggingText()
        Is this a logging text field?
        Returns:
        true if this is a logging text field.

      • isMostRecentFirst

        public boolean isMostRecentFirst()
                          throws mks.frame.triggers.TriggerException
        If this is a logging text field, is it most recent first?
        Returns:
        true if most recent first; false if most recent last.
        Throws:
        mks.frame.triggers.TriggerException - if field is not a logging field.

      • isReadonly

        public boolean isReadonly()
        Is this a readonly field? Readonly fields are those that are builtin to an IM issue and maintained by IM. At the current time, they are:
        • Type
        • Id
        • Created By
        • Created Date
        • Modified By
        • Modified Date
        Returns:
        true if its readonly.

      • getExposedName

        public java.lang.String getExposedName()
        Get the name of this bean: imFieldBean
        Specified by:
        getExposedName in interface mks.frame.triggers.ScriptExposableBean
        Specified by:
        getExposedName in class ScriptBaseBean
        Returns:
        the bean name: imFieldBean.

      • isMultiValued

        public boolean isMultiValued()
        Can this field have multiple values? Pick lists, user and group fields, and relationship fields can all be setup to allow for multiple values.
        Returns:
        true if this field is set to multi-valued

      • getPairedField

        public java.lang.String getPairedField()
        Return the field name of the relationship field paired with this one.

        This call is only valid for a relationship field (i.e. if getFieldType() has the value "relationship"); the results are undefined otherwise.

        Returns:
        A string containing the field name that is paired with this field. Null is returned for a field which does not have a paired field: either a non-relationship field; or a query backed relationship field.

      • isCycleDetection

        public boolean isCycleDetection()
        Is Cycle Detection enabled for this relationship field?

        This call is only valid for a relationship field (i.e. if getFieldType() has the value "relationship"); the results are undefined otherwise.

        Returns:
        true if the cycleDetction flag is set on this relationship field; false otherwise.

      • hasFlag

        public boolean hasFlag​(java.lang.String flagname)
        Does this relationship field contain a link flag of the specified name? For example, if the relationship field had a link flag called Suspect, you could test its existence via: if (!fieldBean.hasFlag("Suspect")).

        This call is only valid for a relationship field (i.e. if getFieldType() has the value "relationship"); the results are undefined otherwise.

        A flag which is disabled is considered to not exist.

        Returns:
        true if the flag exists and is enabled; false otherwise.

      • isComputed

        public boolean isComputed()
        Is this a computed field?
        Returns:
        true if there is a computation associated with this field.

      • getComputation

        public java.lang.String getComputation()
        Return the string representing the computation associated with this field.
        Returns:
        null if this is not a computed field. Otherwise the recreated string representing the computation.

      • getDisplayPattern

        public java.lang.String getDisplayPattern​(java.lang.String typeName)
                                   throws mks.frame.triggers.TriggerException
        Return the string representing the display pattern associated with this field.
        Parameters:
        typeName - the name of the issue type context to use to get the display pattern. Display patterns can be overriden within the type. Null will return the non-overridden display pattern for the field
        Returns:
        null if this is not a numeric field or no pattern has been set. Otherwise the string representing the display pattern.
        Throws:
        mks.frame.triggers.TriggerException - An appropriate error message is returned in a TriggerException if the type name is invalid.

      • isFieldValueRichContent

        public boolean isFieldValueRichContent​(java.lang.String value)
                                throws mks.frame.triggers.TriggerException
        Determine if a string provided is a rich text value, in the context of this field.
        Parameters:
        value - The field value.
        Returns:
        true if the field value should be interpreted as a text field value that is rich content, false otherwise.
        Throws:
        mks.frame.triggers.TriggerException - Reserved exception, not currently used.

      • getStoreToHistoryFrequency

        public int getStoreToHistoryFrequency()
        Is this field stored to history periodically? What is the period?
        Returns:
        0 if not stored (or manual); 1 for daily, 2 for weekly, 3 if stored to history monthly, 4 if store to history on delta.

      • isStaticallyComputed

        public boolean isStaticallyComputed()
        Is this a statically computed field? A statically computed field is one where the history computation also stores the result to the issue record; the computation is only performed at the point which it is computed; all queries and all issue display works on the last computed value.
        Returns:
        true if the field is statically computed.

      • isTrace

        public boolean isTrace()
        Is the trace flag on for this field?
        Returns:
        true in one of the following cases
        • The field is of type relationship and has the trace flag on
        • The field is of type source trace and follows traces
        or false in all other cases

      • getDisplayTrueAs

        public java.lang.String getDisplayTrueAs()
        Return the custom value that represents how the true value displays in a logical field.
        Returns:
        the true custom value if this is a logical field and a custom true value is set. Null otherwise.

      • getDisplayFalseAs

        public java.lang.String getDisplayFalseAs()
        Return the custom value that represents how the false value displays in a logical field.
        Returns:
        the false custom value if this is a logical field and a custom false value is set. Null otherwise.

      • computeHistoryNow

        public void computeHistoryNow()
                       throws mks.frame.triggers.TriggerException
        Compute a computed field now, and store its new value to history. If it is a statically computed field, update the issue record for the field as well. Note that this computation does not partake in the current transaction: if this method does not throw an exception then the values have been successfully computed and stored for all appropriate issues.
        Throws:
        mks.frame.triggers.TriggerException - If the field is not a computed field or on error computing the history for the field.

      • computeHistoryNow

        public void computeHistoryNow​(int[] ids)
                       throws mks.frame.triggers.TriggerException
        Compute a computed field now, and store its new value to history. If it is a statically computed field, update the issue record for the field as well. Note that this computation does not partake in the current transaction: if this method does not throw an exception then the values have been successfully computed and stored for all appropriate issues.

        Prior to the Integrity Server release 10.3, all updated values were committed as one -- in other words, either all succeed, or all fail. In certain cases, this results in the locking of the items being updated; hence users are unable to edit those items until the entire transaction has been committed. In 10.3, this was changed to attempt to commit every five seconds. This releases the item locks, allowing users to edit them. However, this does mean that this method is no longer fully transactional -- a failure will now only discard the items since the last database commit. Note also that it may not be possible to commit every five seconds -- for example if the number of rows fetched from the database at a time requires more than five seconds to compute.

        Parameters:
        ids - an array of integers, being the issue ids to recompute. The value may be null, to recompute for all appropriate issues. If the value is null, then the last compute time for the field is set.
        Throws:
        mks.frame.triggers.TriggerException - If the field is not a computed field or on error computing the history for the field.