com.crystaldecisions.sdk.occa.report.data
Class ParameterField

java.lang.Object
  extended bycom.crystaldecisions.sdk.occa.report.data.Field
      extended bycom.crystaldecisions.sdk.occa.report.data.ParameterField
All Implemented Interfaces:
IClone, IField, IParameterField

public class ParameterField
extends Field
implements IParameterField, IClone

This object enables you to get and set values for the parameter field. When possible, use the IParameterField interface to manipulate this object. Parameters prompt the user of a report to enter information.

Think of a parameter as a question that the user needs to answer before the report is generated. The information users enter, or the way they respond, determines what appears in the report. For example, in a report used by sales people, there might be a parameter that asks the user to choose a region. The report would return the results for the specific region instead of returning the results for all of the regions.

By using parameter fields in formulas, selection formulas, and in the report itself, you can create a single report that you can modify whenever your needs change. Parameter fields can also be used in subreports. Parameter values are discrete or ranged. A discrete value represents a particular, single value, while a range value represents a value between a certain range. Additionally, parameters can have one value (discrete or ranged) or multiple values (discrete or ranged).

The ParameterField object allows you to manipulate a parameter in the report.


Constructor Summary
ParameterField()
           
ParameterField(IParameterField src)
           
 
Method Summary
 java.lang.Object clone(boolean deepClone)
          Returns the new object that has been cloned.
 void copyTo(java.lang.Object destObject, boolean deepCopy)
          Copies the object.
 java.lang.Object createMember(java.lang.String eleName, org.xml.sax.Attributes attrs, XMLSerializationContext ctxt, java.util.Map objState, boolean[] bLoaded)
          For internal use only.
 void endElement(java.lang.String eleName, java.util.Map objState)
          For internal use only.
 boolean getAllowCustomCurrentValues()
          Returns true if the user can enter custom values for a parameter when the report is refreshed and false otherwise.
 boolean getAllowMultiValue()
          Returns true whether the user can select more than one value for a parameter when the report is refreshed; returns false if the user can only choose one value for the parameter.
 boolean getAllowNullValue()
           Returns true if the value for the parameter may be null and false otherwise.
 IField getBrowseField()
          Returns the database field whose values are being used as default values for the parameter.
 Values getCurrentValues()
           Returns the values that are currently being used for the parameter.
 ParameterDefaultValueDisplayType getDefaultValueDisplayType()
           For internal use only.
 Values getDefaultValues()
          Returns the default values that may be used for the parameter.
 ParameterSortMethod getDefaultValueSortMethod()
          Returns whether the default values are sorted by value or by the value's description.
 ParameterSortOrder getDefaultValueSortOrder()
          Returns the manner in which the values or the values' descriptions are sorted.
 java.lang.String getEditMask()
           Returns the edit mask for the parameter values.
 FieldKind getKind()
           Returns what kind of field this is.
 IParameterFieldDiscreteValue getMaximumValue()
          Returns the maximum value the parameter can have, providing that a minimum value is also specified.
 IParameterFieldDiscreteValue getMinimumValue()
          Returns the minimum value the parameter can have, providing that a maximum value is also specified.
 ParameterFieldType getParameterType()
          Returns how the parameter is being used--that is, its type.
 java.lang.String getReportName()
          Returns the name of the report to which the parameter belongs.
 java.lang.String getShortName(java.util.Locale locale)
           Returns the short name of the field.
 int getUsage()
           For internal use only.
 ParameterValueRangeKind getValueRangeKind()
          Returns whether the parameter is discrete, ranged, or both.
 Values getValues()
          Returns the current values for the parameter, or the default values if no current values are defined.
 boolean hasContent(java.lang.Object srcParameterField)
          Returns true if this object contains the same elements as the passed in object.
 void readElement(java.lang.String eleName, java.lang.String sVal, org.xml.sax.Attributes attrs, java.util.Map objState)
          For internal use only.
 void save(XMLWriter writer, java.lang.String sTag, XMLSerializationContext ctxt)
          For internal use only.
 void save(XMLWriter writer, XMLSerializationContext ctxt)
          For internal use only.
 void saveContents(XMLWriter writer, XMLSerializationContext ctxt)
          For internal use only.
 void setAllowCustomCurrentValues(boolean allowCustomCurrentValues)
          Sets if the user can enter custom values for a parameter when the report is refreshed.
 void setAllowMultiValue(boolean allowMultiValue)
          Sets whether the user can select more than one value for a parameter when the report is refreshed.
 void setAllowNullValue(boolean allowNullValue)
           Set to true if the value for the parameter may be null and false otherwise.
 void setBrowseField(IField browseField)
          Sets the database field whose values are being used as default values for the parameter.
 void setCurrentValues(Values currentValues)
          Sets the values that are currently being used for the parameter.
 void setDefaultValueDisplayType(ParameterDefaultValueDisplayType type)
           For internal use only.
 void setDefaultValues(Values defaultValues)
          Sets the default values that may be used for the parameter.
 void setDefaultValueSortMethod(ParameterSortMethod defaultValueSortMethod)
          Sets whether the default values are sorted by value or by the value's description.
 void setDefaultValueSortOrder(ParameterSortOrder defaultValueSortOrder)
          Sets the manner in which the values or the values' descriptions are sorted.
 void setEditMask(java.lang.String editMask)
           Sets the edit mask for the parameter values.
 void setMaximumValue(IParameterFieldDiscreteValue maximumValue)
          Sets the maximum value the parameter can have, providing that a minimum value is also specified.
 void setMinimumValue(IParameterFieldDiscreteValue minimumValue)
          Sets the minimum value the parameter can have, providing that a maximum value is also specified.
 void setParameterType(ParameterFieldType parameterType)
          Sets how the parameter is being used--that is, its type.
 void setReportName(java.lang.String reportName)
          Sets the name of the report to which the parameter belongs.
 void setUsage(int usage)
           For internal use only.
 void setValueRangeKind(ParameterValueRangeKind valueRangeKind)
          Sets whether the parameter is discrete, ranged, or both.
 void startElement(java.lang.String eleName, java.util.Map objState, org.xml.sax.Attributes attrs)
          For internal use only.
 
Methods inherited from class com.crystaldecisions.sdk.occa.report.data.Field
createMember, getDescription, getDisplayName, getFormulaForm, getHeadingText, getIsRecurring, getLength, getLongName, getName, getType, save, save, setDescription, setHeadingText, setLength, setName, setType
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.crystaldecisions.sdk.occa.report.data.IField
getDescription, getDisplayName, getFormulaForm, getHeadingText, getIsRecurring, getLength, getLongName, getName, getType, setDescription, setHeadingText, setLength, setName, setType
 

Constructor Detail

ParameterField

public ParameterField(IParameterField src)

ParameterField

public ParameterField()
Method Detail

clone

public java.lang.Object clone(boolean deepClone)
Description copied from interface: IClone

Returns the new object that has been cloned.

Specified by:
clone in interface IClone
Overrides:
clone in class Field

copyTo

public void copyTo(java.lang.Object destObject,
                   boolean deepCopy)
Description copied from interface: IClone

Copies the object.

Specified by:
copyTo in interface IClone
Overrides:
copyTo in class Field

createMember

public java.lang.Object createMember(java.lang.String eleName,
                                     org.xml.sax.Attributes attrs,
                                     XMLSerializationContext ctxt,
                                     java.util.Map objState,
                                     boolean[] bLoaded)

For internal use only.

Overrides:
createMember in class Field

endElement

public void endElement(java.lang.String eleName,
                       java.util.Map objState)

For internal use only.

Overrides:
endElement in class Field

getAllowCustomCurrentValues

public boolean getAllowCustomCurrentValues()
Description copied from interface: IParameterField

Returns true if the user can enter custom values for a parameter when the report is refreshed and false otherwise. If this property is true, users can enter any value for the parameter. If it is false, they must choose from one of the default values.

Specified by:
getAllowCustomCurrentValues in interface IParameterField
Returns:
true if the user can enter custom values for a parameter when the report is refreshed, and false otherwise.

getAllowMultiValue

public boolean getAllowMultiValue()
Description copied from interface: IParameterField

Returns true whether the user can select more than one value for a parameter when the report is refreshed; returns false if the user can only choose one value for the parameter.

Specified by:
getAllowMultiValue in interface IParameterField
Returns:
true if the user can select more than one value for a parameter when the report is refreshed, and false otherwise.

getAllowNullValue

public boolean getAllowNullValue()
Description copied from interface: IParameterField

Returns true if the value for the parameter may be null and false otherwise. This is used only for stored SQL procedures.

Specified by:
getAllowNullValue in interface IParameterField
Returns:
true if the value for the parameter may be null, and false otherwise.

getBrowseField

public IField getBrowseField()
Description copied from interface: IParameterField

Returns the database field whose values are being used as default values for the parameter. This is used for UI-display purposes.

Specified by:
getBrowseField in interface IParameterField
Returns:
The database field whose values are being used as default values for the parameter as an IField interface.

getCurrentValues

public Values getCurrentValues()
Description copied from interface: IParameterField

Returns the values that are currently being used for the parameter. To permanently set this value, a Report Application Server is required. Please consult the Crystal Reports Java Reporting Component Developer's Guide for more information.

Specified by:
getCurrentValues in interface IParameterField
Returns:
The current values as a Values object.

getDefaultValueDisplayType

public ParameterDefaultValueDisplayType getDefaultValueDisplayType()

For internal use only.

Specified by:
getDefaultValueDisplayType in interface IParameterField

getDefaultValues

public Values getDefaultValues()
Description copied from interface: IParameterField

Returns the default values that may be used for the parameter.

Specified by:
getDefaultValues in interface IParameterField
Returns:
The default values that may be used for the parameter as a Values object.

getDefaultValueSortMethod

public ParameterSortMethod getDefaultValueSortMethod()
Description copied from interface: IParameterField

Returns whether the default values are sorted by value or by the value's description. This is used for UI-display purposes.

Specified by:
getDefaultValueSortMethod in interface IParameterField
Returns:
Whether the default values are sorted by value or by the value's description as a ParameterSortMethod object.

getDefaultValueSortOrder

public ParameterSortOrder getDefaultValueSortOrder()
Description copied from interface: IParameterField

Returns the manner in which the values or the values' descriptions are sorted.

Specified by:
getDefaultValueSortOrder in interface IParameterField
Returns:
The manner in which the values or the values' descriptions are sorted as a ParameterSortOrder object.

getEditMask

public java.lang.String getEditMask()
Description copied from interface: IParameterField

Returns the edit mask for the parameter values. This is used for UI-display purposes. The edit mask can be any of a set of masking characters used to restrict the values you can enter as parameter values. The edit mask also limits the values you can enter as default prompting values.

Note: The value of the edit mask is not checked if you use the SDK to change parameter values. You must check to ensure that any values the user enters respect the edit mask. If a user enters an invalid value according to the edit mask, it will not be possible to view or schedule the report.

The edit mask follows the following guidelines:

Note: Some of the edit mask characters require that you enter a character in their place (when entering a parameter value), while others allow you to leave a space, if needed. For example, if the edit mask is 000099, you can enter a parameter value with four digits, five digits, or six digits, since the '9' edit mask character does not require the entry of a character. However, since '0' does require such an entry, you could not enter a parameter value with less than four digits.

Specified by:
getEditMask in interface IParameterField
Returns:
The edit mask as a String.

getKind

public FieldKind getKind()
Description copied from interface: IField

Returns what kind of field this is. Do not confuse this property with Type. Kind identifies what sort of report field this is, while Type identifies what the field is composed of. For example, a bitmap, string, chart, number, date, and so on.

Specified by:
getKind in interface IField
Returns:
A String that specifies what kind of field this is.

getMaximumValue

public IParameterFieldDiscreteValue getMaximumValue()
Description copied from interface: IParameterField

Returns the maximum value the parameter can have, providing that a minimum value is also specified.

If the parameter is discrete, the discrete values must be between the minimum and maximum values. If the parameter has a range limit, both the maximum and minimum values are defined. The BeginValue and/or EndValue of each ranged value must be between the minimum and maximum values.

If the parameter is a number, this property represents the largest allowable number the parameter may have. If it is a string, this is the maximum length the string may be. If it is a Date/Time value, this is the earliest date and time the parameter may be. This property does not apply to Boolean values.

Specified by:
getMaximumValue in interface IParameterField
Returns:
The IParameterFieldDiscreteValue object.

getMinimumValue

public IParameterFieldDiscreteValue getMinimumValue()
Description copied from interface: IParameterField

Returns the minimum value the parameter can have, providing that a maximum value is also specified.

If the parameter is discrete, the discrete values must be between the minimum and maximum values. If the parameter has a range limit, both the maximum and minimum values are defined. The BeginValue and/or EndValue of each ranged value must be between the minimum and maximum values.

If the parameter is a number, this property represents the smallest allowable number the parameter may have. If it is a string, this is the minimum length the string may be. If it is a Date/Time value, this is the earliest date and time the parameter may be. This property does not apply to Boolean values.

Specified by:
getMinimumValue in interface IParameterField
Returns:
The IParameterFieldDiscreteValue object.

getParameterType

public ParameterFieldType getParameterType()
Description copied from interface: IParameterField

Returns how the parameter is being used--that is, its type.

Specified by:
getParameterType in interface IParameterField
Returns:
The parameter field type as a ParameterFieldType object.

getReportName

public java.lang.String getReportName()
Description copied from interface: IParameterField

Returns the name of the report to which the parameter belongs. This string is empty if the parameter belongs in a main report; if the parameter is contained in a subreport, this contains the name of the subreport.

Specified by:
getReportName in interface IParameterField
Returns:
The name of the report as a String.

getShortName

public java.lang.String getShortName(java.util.Locale locale)
Description copied from interface: IField

Returns the short name of the field.

Specified by:
getShortName in interface IField
Overrides:
getShortName in class Field

getUsage

public int getUsage()

For internal use only.


getValueRangeKind

public ParameterValueRangeKind getValueRangeKind()
Description copied from interface: IParameterField

Returns whether the parameter is discrete, ranged, or both.

Specified by:
getValueRangeKind in interface IParameterField
Returns:
Whether the parameter is discrete, ranged, or both as a ParameterValueRangeKind object.

getValues

public Values getValues()
Description copied from interface: IParameterField

Returns the current values for the parameter, or the default values if no current values are defined. This is equivalent to the IParameterField.getCurrentValues() method unless it is empty, in which case it is equivalent to the IParameterField.getDefaultValues() method.

Specified by:
getValues in interface IParameterField
Returns:
The values as a Values object.

hasContent

public boolean hasContent(java.lang.Object srcParameterField)
Description copied from interface: IClone

Returns true if this object contains the same elements as the passed in object.

Specified by:
hasContent in interface IClone
Overrides:
hasContent in class Field

readElement

public void readElement(java.lang.String eleName,
                        java.lang.String sVal,
                        org.xml.sax.Attributes attrs,
                        java.util.Map objState)

For internal use only.

Overrides:
readElement in class Field

save

public void save(XMLWriter writer,
                 XMLSerializationContext ctxt)
          throws java.io.IOException

For internal use only.

Overrides:
save in class Field
Throws:
java.io.IOException

save

public void save(XMLWriter writer,
                 java.lang.String sTag,
                 XMLSerializationContext ctxt)
          throws java.io.IOException

For internal use only.

Overrides:
save in class Field
Throws:
java.io.IOException

saveContents

public void saveContents(XMLWriter writer,
                         XMLSerializationContext ctxt)
                  throws java.io.IOException

For internal use only.

Overrides:
saveContents in class Field
Throws:
java.io.IOException

setAllowCustomCurrentValues

public void setAllowCustomCurrentValues(boolean allowCustomCurrentValues)
Description copied from interface: IParameterField

Sets if the user can enter custom values for a parameter when the report is refreshed. If this property is true, users can enter any value for the parameter. If it is false, they must choose from one of the default values.

Specified by:
setAllowCustomCurrentValues in interface IParameterField
Parameters:
allowCustomCurrentValues - true if the user can enter custom values for a parameter when the report is refreshed, and false otherwise.

setAllowMultiValue

public void setAllowMultiValue(boolean allowMultiValue)
Description copied from interface: IParameterField

Sets whether the user can select more than one value for a parameter when the report is refreshed.

Specified by:
setAllowMultiValue in interface IParameterField
Parameters:
allowMultiValue - true if the user can select more than one value for a parameter when the report is refreshed, and false otherwise.

setAllowNullValue

public void setAllowNullValue(boolean allowNullValue)
Description copied from interface: IParameterField

Set to true if the value for the parameter may be null and false otherwise. This is used only for stored SQL procedures.

Specified by:
setAllowNullValue in interface IParameterField
Parameters:
allowNullValue - true if the value for the parameter may be null, and false otherwise.

setBrowseField

public void setBrowseField(IField browseField)
Description copied from interface: IParameterField

Sets the database field whose values are being used as default values for the parameter. This is used for UI-display purposes.

Specified by:
setBrowseField in interface IParameterField
Parameters:
browseField - The database field whose values are being used as default values for the parameter as an IField interface.

setCurrentValues

public void setCurrentValues(Values currentValues)
Description copied from interface: IParameterField

Sets the values that are currently being used for the parameter. To permanently set this value, a Report Application Server is required. Please consult the Crystal Reports Java Reporting Component Developer's Guide for more information.

Specified by:
setCurrentValues in interface IParameterField
Parameters:
currentValues - The current values as a Values object.

setDefaultValueDisplayType

public void setDefaultValueDisplayType(ParameterDefaultValueDisplayType type)

For internal use only.

Specified by:
setDefaultValueDisplayType in interface IParameterField

setDefaultValues

public void setDefaultValues(Values defaultValues)
Description copied from interface: IParameterField

Sets the default values that may be used for the parameter.

Specified by:
setDefaultValues in interface IParameterField
Parameters:
defaultValues - The default values that may be used for the parameter as a Values object.

setDefaultValueSortMethod

public void setDefaultValueSortMethod(ParameterSortMethod defaultValueSortMethod)
Description copied from interface: IParameterField

Sets whether the default values are sorted by value or by the value's description. This is used for UI-display purposes.

Specified by:
setDefaultValueSortMethod in interface IParameterField
Parameters:
defaultValueSortMethod - Whether the default values are sorted by value or by the value's description as a ParameterSortMethod object.

setDefaultValueSortOrder

public void setDefaultValueSortOrder(ParameterSortOrder defaultValueSortOrder)
Description copied from interface: IParameterField

Sets the manner in which the values or the values' descriptions are sorted.

Specified by:
setDefaultValueSortOrder in interface IParameterField
Parameters:
defaultValueSortOrder - The manner in which the values or the values' descriptions are sorted as a ParameterSortOrder object.

setEditMask

public void setEditMask(java.lang.String editMask)
Description copied from interface: IParameterField

Sets the edit mask for the parameter values. This is used for UI-display purposes. The edit mask can be any of a set of masking characters used to restrict the values you can enter as parameter values. The edit mask also limits the values you can enter as default prompting values.

Note: The value of the edit mask is not checked if you use the SDK to change parameter values. You must check to ensure that any values the user enters respect the edit mask. If a user enters an invalid value according to the edit mask, it will not be possible to view or schedule the report.

The edit mask follows the following guidelines:

Note: Some of the edit mask characters require that you enter a character in their place (when entering a parameter value), while others allow you to leave a space, if needed. For example, if the Edit Mask is 000099, you can enter a parameter value with four digits, five digits, or six digits, since the '9' edit mask character does not require the entry of a character. However, since '0' does require such an entry, you could not enter a parameter value with less than four digits.

Specified by:
setEditMask in interface IParameterField
Parameters:
editMask - The edit mask as a String.

setMaximumValue

public void setMaximumValue(IParameterFieldDiscreteValue maximumValue)
Description copied from interface: IParameterField

Sets the maximum value the parameter can have, providing that a minimum value is also specified.

If the parameter is discrete, the discrete values must be between the minimum and maximum values. If the parameter has a range limit, both the maximum and minimum values are defined. The BeginValue and/or EndValue of each ranged value must be between the minimum and maximum values.

If the parameter is a number, this property represents the largest allowable number the parameter may have. If it is a string, this is the maximum length the string may be. If it is a Date/Time value, this is the earliest date and time the parameter may be. This property does not apply to Boolean values.

Specified by:
setMaximumValue in interface IParameterField
Parameters:
maximumValue - The IParameterFieldDiscreteValue object.

setMinimumValue

public void setMinimumValue(IParameterFieldDiscreteValue minimumValue)
Description copied from interface: IParameterField

Sets the minimum value the parameter can have, providing that a maximum value is also specified.

If the parameter is discrete, the discrete values must be between the minimum and maximum values. If the parameter has a range limit, both the maximum and minimum values are defined. The BeginValue and/or EndValue of each ranged value must be between the minimum and maximum values.

If the parameter is a number, this property represents the smallest allowable number the parameter may have. If it is a string, this is the minimum length the string may be. If it is a Date/Time value, this is the earliest date and time the parameter may be. This property does not apply to Boolean values.

Specified by:
setMinimumValue in interface IParameterField
Parameters:
minimumValue - The IParameterFieldDiscreteValue object.

setParameterType

public void setParameterType(ParameterFieldType parameterType)
Description copied from interface: IParameterField

Sets how the parameter is being used--that is, its type.

Specified by:
setParameterType in interface IParameterField
Parameters:
parameterType - The parameter field type as a ParameterFieldType object.

setReportName

public void setReportName(java.lang.String reportName)
Description copied from interface: IParameterField

Sets the name of the report to which the parameter belongs. This string is empty if the parameter belongs in a main report; if the parameter is contained in a subreport, this contains the name of the subreport.

Specified by:
setReportName in interface IParameterField
Parameters:
reportName - The name of the report as a String. Set this string as empty if the parameter belongs in a main report; if the parameter is contained in a subreport, set this to contain the name of the subreport.

setUsage

public void setUsage(int usage)

For internal use only.


setValueRangeKind

public void setValueRangeKind(ParameterValueRangeKind valueRangeKind)
Description copied from interface: IParameterField

Sets whether the parameter is discrete, ranged, or both.

Specified by:
setValueRangeKind in interface IParameterField
Parameters:
valueRangeKind - Whether the parameter is discrete, ranged, or both as a ParameterValueRangeKind object.

startElement

public void startElement(java.lang.String eleName,
                         java.util.Map objState,
                         org.xml.sax.Attributes attrs)

For internal use only.

Overrides:
startElement in class Field