Class TaxControl

  • All Implemented Interfaces:
    java.lang.Runnable

    public class TaxControl
    extends java.lang.Object
    implements java.lang.Runnable
    The TaxControl JavaBean allows computation of payroll withholding taxes. This component contains a few key properties which are most often used. These properties are explained here.

    All Tax Table data is provided in a separate data file (typically "us.dat"), which is updated as needed. It is essential that setDataFilename is called to properly designate this file.

    Because there are many taxes within the tax table data, the developer must specify which tax is to be computed. This is accomplished by naming the desired tax in the setSelectedTax call. The computed tax is returned by the getTaxAmount method.

    In order to provide tax figures, several vital employee information items must be supplied by setting properties. The key properties required for most tax computations are:
    1. setEarnings
    2. setExemptions
    3. setFilingStatus
    Other input items, such as the Miscellaneous, Auxiliary, YTDEarnings, StateExemptions, or Supplemental properties may be required for certain taxes or special situations.

    The principle output method is
    The other output items such as Instructions, WithheldTax, etc., are informational only, and not related to actual calculation of withholding taxes.
    Since:
    JDK1.6
    Version:
    2.6.1
    Author:
    Caliber Technology LLC
    See Also:
    setDataFilename(java.lang.String), setEarnings(float), setExemptions(int), setFilingStatus(int), getTaxAmount()
    • Constructor Summary

      Constructors 
      Constructor Description
      TaxControl()
      Default constructor
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void clear()
      Unloads all table information.
      boolean downloadTable​(java.lang.String userName, java.lang.String password)  
      boolean downloadTable​(java.lang.String userName, java.lang.String password, boolean level2)
      Replaces the Tax Table named in the DataFilename property with current version downloaded from the TaxUpdate Web Site.
      float getAuxiliary()
      Gets the "Auxiliary" value.
      int getCompanyZip()
      Gets the company's main workplace ZIP code.
      java.lang.String getDataFilename()
      Indicates the Tax Table file name.
      float getEarnings()
      Gets employee's earnings setting.
      int getExemptions()
      Gets employee's Federal exemptions.
      int getFilingStatus()
      Retrieves filing status of employee.
      java.lang.String getInstructions()
      Instructions which correspond to the selected tax (read-only).
      static java.lang.String[] getJSONArray​(java.lang.String json)  
      static java.lang.String getJSONError​(java.lang.String json)  
      static java.lang.String getJSONStatus​(java.lang.String json)  
      static java.lang.String getJSONString​(java.lang.String name, java.lang.String json)  
      float getMiscellaneous()
      Gets the "Miscellaneous" value, used for state and local tax special data needs.
      java.util.Date getPayDate()
      Date on the paycheck.
      int getPayPeriodsPerYear()
      The number of pay periods in a year.
      long getPsd()
      Returns a PSD Code for the currently selected tax, if applicable.
      java.lang.String getPublished()
      Publication information for the selected tax (read-only).
      java.lang.String getSelectedTax()
      Gets the tax for computation.
      java.lang.String getSoftwareVersion()
      TaxControls software version.
      int getStateExemptions()
      Returns employee's state exemptions.
      int getStateFilingStatus()
      Retrieves filing status of employee for state withholding.
      java.lang.String getStreetQuery​(int zip, java.lang.String search, java.lang.String username, java.lang.String password)
      Returns a newline and comma-delimited String containing suggested street name matches within a ZIP Code.
      float getTaxableWages()
      Returns the taxable wages.
      float getTaxAmount()
      Returns the calculated tax amount.
      float getTaxBracket()
      Returns the calculated tax bracket.
      Taxes getTaxes()
      Returns the Taxes object associated with this control.
      Taxes getTaxesForZip​(int workZip, int homeZip)
      Returns a Taxes object containing suggested State, Local and Other (usually Unemployment) taxes applicable to a set of zip codes.
      java.lang.String getTaxNamesForZip​(int workZip, int homeZip)
      Returns a comma-delimited String containing suggested State, Local and Other (usually Unemployment) taxes applicable to a set of zip codes.
      java.lang.String getTaxQuery​(int zipwork, java.lang.String streetwork, int numwork, int ziphome, java.lang.String streethome, int numhome, java.lang.String username, java.lang.String password)
      Returns a comma-delimited String containing suggested State, Local and Other (usually Unemployment) taxes applicable to work and residence addresses.
      java.lang.String getTaxQuery​(java.lang.String workAddress, java.lang.String homeAddress)
      Returns a comma-delimited String containing suggested State, Local and Other (usually Unemployment) taxes applicable to work and residence addresses.
      java.lang.String getTaxQuery​(java.lang.String workAddress, java.lang.String homeAddress, java.lang.String nexus)  
      java.lang.String getTaxType()
      Retrieves type of the currently selected tax.
      float getUnemploymentRate()
      Gets the rate to be used for unemployment tax calculations.
      java.lang.String getVersion()
      Get the version number of the tax table.
      java.lang.String getWebServiceAddress()
      Returns the TaxQuery web service url.
      java.lang.String getXMLInstructions()
      XML-formatted Instructions which correspond to the selected tax (read-only).
      float getYTDEarnings()
      Used to indicate year-to-date amounts earned previous to current earnings.
      float getYTDTax()
      Gets the Amount of tax paid year-to-date, not including the current pay period.
      boolean isAutoUnlock()
      Indicates whether or not the control should prompt before attempting to unlock a new Tax Table file.
      boolean isDiscontinued()
      Indicates whether the selected tax has been discontinue.
      boolean isRoundingOptional()
      Indicates whether the selected tax can been rounded to the nearest dollar amount (read-only).
      boolean isRoundingRequired()
      Indicates whether the selected tax has been rounded to the nearest dollar amount (read-only).
      boolean isRoundWhenOptional()
      Returns value of RoundWhenOption field.
      boolean isSupplemental()
      Returns "Supplemental" property, which indicates whether the Earnings property contains supplemental earnings.
      boolean isTableCurrent()
      Returns True if the Tax Table named in the DataFilename property is current.
      boolean isWithheldTax()
      Indicates whether the selected tax has should be withheld from the employee's pay.
      void refresh​(boolean background)
      Forces the control to read the tax table named by the DataFilename property.
      void run()
      For internal use only.
      void setAutoUnlock​(boolean autoUnlock)
      Indicates whether or not the control should prompt before attempting to unlock a new Tax Table file.
      void setAuxiliary​(double auxiliary)  
      void setAuxiliary​(float auxiliary)
      Sets the "Auxiliary" value, which is used for state and local tax special data needs.
      void setCompanyZip​(int Zip)
      Sets the company's main workplace ZIP code.
      void setDataFilename​(java.lang.String dataFilename)
      Indicates the Tax Table file name.
      void setEarnings​(double earnings)  
      void setEarnings​(float earnings)
      Sets employee's taxable earnings.
      void setExemptions​(int exemptions)
      Sets employee's Federal exemptions.
      void setFilingStatus​(int filingStatus)
      Sets filing status of employee.
      void setMiscellaneous​(double miscellaneous)  
      void setMiscellaneous​(float miscellaneous)
      Sets the "Miscellaneous" value, used for state and local tax special data needs.
      void setPayDate​(java.util.Date d)
      Sets the check pay date.
      void setPayPeriodsPerYear​(int payPeriodsPerYear)  
      void setRoundWhenOptional​(boolean round)
      Sets the value of RoundWhenOptional field.
      void setSelectedTax​(java.lang.String selectedTax)
      Sets the tax for computation.
      void setStateExemptions​(int stateExemptions)
      Sets employee's state exemptions.
      void setStateFilingStatus​(int filingStatus)
      Sets filing status of employee for state withholding.
      void setSupplemental​(boolean supplemental)
      Sets "Supplemental" property, which indicates whether the Earnings property contains supplemental earnings.
      void setUnemploymentRate​(double rate)
      Sets the rate to be used for unemployment tax calculations.
      void setUnemploymentRate​(float rate)
      Sets the rate to be used for unemployment tax calculations.
      void setWebServiceAddress​(java.lang.String url)
      Sets the TaxQuery web service url.
      void setYTDEarnings​(double YTDEarnings)
      Sets the year-to-date amount of earnings.
      void setYTDEarnings​(float YTDEarnings)
      Used to indicate year-to-date amounts earned previous to current earnings.
      void setYTDTax​(double YTDTax)
      Sets the year-to-date tax paid.
      void setYTDTax​(float YTDTax)
      Used to indicate year-to-date tax amount paid previous to current pay period.
      void showAboutBox()
      Show the control's About box.
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • TaxControl

        public TaxControl()
        Default constructor
    • Method Detail

      • run

        public void run()
        For internal use only.
        Specified by:
        run in interface java.lang.Runnable
      • refresh

        public void refresh​(boolean background)
                     throws TaxControlException
        Forces the control to read the tax table named by the DataFilename property. The data can be loaded in the background by a separate thread if desired.
        Parameters:
        background - True if read operation should occur in the background.
        Throws:
        TaxControlException - if DataFilename is invalid or tax table is corrupted.
      • clear

        public void clear()
        Unloads all table information.
      • downloadTable

        public boolean downloadTable​(java.lang.String userName,
                                     java.lang.String password,
                                     boolean level2)
                              throws java.io.IOException,
                                     TaxControlException
        Replaces the Tax Table named in the DataFilename property with current version downloaded from the TaxUpdate Web Site. Internet Access is required to use this property.
        An application may automatically download the most current tax table from the Caliber Technology Inc. web site using the DownloadTable Method. To minimize delay and network traffic, the application should first check the IsTableCurrent Property to determine if the local Tax Table needs to be updated.
        Parameters:
        String - username assigned by Caliber Technology LLC
        String - password assigned by Caliber Technology LLC
        boolean - level2, true for level 2 taxfile, false for level 1
        Returns:
        boolean True if tax table was successfully downloaded
        Throws:
        java.io.IOException - Thrown if network problems prevent downloading.
        TaxControlException
        See Also:
        isTableCurrent()
      • downloadTable

        public boolean downloadTable​(java.lang.String userName,
                                     java.lang.String password)
                              throws java.io.IOException,
                                     TaxControlException
        Throws:
        java.io.IOException
        TaxControlException
      • getTaxNamesForZip

        public java.lang.String getTaxNamesForZip​(int workZip,
                                                  int homeZip)
                                           throws TaxControlException
        Returns a comma-delimited String containing suggested State, Local and Other (usually Unemployment) taxes applicable to a set of zip codes.
        Parameters:
        workZip - int Work zip code.
        homeZip - int Home zip code.
        Returns:
        String Comma-delimited String of tax names.
        Throws:
        TaxControlException - if DataFilename is invalid.
        See Also:
        getTaxesForZip(int, int)
      • getPsd

        public long getPsd()
                    throws TaxControlException
        Returns a PSD Code for the currently selected tax, if applicable. Otherwise returns 0. PSD Codes apply only to PA local EIT's.
        Returns:
        long PSD Code
        Throws:
        TaxControlException - if DataFilename is invalid.
      • getTaxesForZip

        public Taxes getTaxesForZip​(int workZip,
                                    int homeZip)
                             throws TaxControlException
        Returns a Taxes object containing suggested State, Local and Other (usually Unemployment) taxes applicable to a set of zip codes. Federal taxes are not included, as these are trivial to add, and SECA vs FICA can't be determined by zip code. While not all zip codes fall within a single local tax jurisdiction, in most cases the results here will be correct. Work and Home zip codes are supplied in order to detect Resident status for local jurisdictions, as well as special cases involving PA and MD jurisdictions. Note that zip codes are represented as int's, and that leading 0's are not necessary (e.g., "07450" is represented as 7450).
        Parameters:
        workZip - int Work zip code.
        homeZip - int Home zip code.
        Returns:
        Taxes Collection of tax objects.
        Throws:
        TaxControlException - if DataFilename is invalid.
      • setCompanyZip

        public void setCompanyZip​(int Zip)
        Sets the company's main workplace ZIP code. Setting this value allows the automatic computation of FUTA credits, which must take state unemployment taxes into account. If more than one workplace state must be considered, then this value must be set accordingly before FUTA is calculated.
        Parameters:
        Zip - The ZIP code (as an integer) of the company's main workplace
      • getCompanyZip

        public int getCompanyZip()
        Gets the company's main workplace ZIP code.
        Returns:
        int Company's ZIP code as an integer.
        See Also:
        setCompanyZip(int)
      • getVersion

        public java.lang.String getVersion()
                                    throws TaxControlException
        Get the version number of the tax table. The Version property provides the user with a manual method of identifying the most recent Tax Table data. All data files are published with seqentially increasing Version numbers. When new Tax Table files are released, the Version number is indicated on the "Download" web page alongside the file link. The download page may be found at

        https://www.taxupdate.com/download

        A similar field, the Published property, indicates publication information corresponding to the tax selected by the setSelectedTax method.
        Returns:
        String Version number of currently openned tax table.
        Throws:
        TaxControlException - if Tax Table cannot be openned.
        See Also:
        setSelectedTax(java.lang.String), Taxes.getVersion(), Tax.getPublished()
      • getTaxes

        public Taxes getTaxes()
                       throws TaxControlException
        Returns the Taxes object associated with this control. The Taxes object is a collection of Tax objects, which can be individually accessed by the developer.
        Returns:
        Taxes Taxes object.
        Throws:
        TaxControlException - thrown if Taxes object cannot be generated.
        See Also:
        Taxes
      • getTaxAmount

        public float getTaxAmount()
                           throws TaxControlException
        Returns the calculated tax amount. This method returns the employee's computed tax, expressed in terms of the pay period established by the PayPeriodsPerYear property. In other words, if PayPeriodsPerYear is set to 12 (the default), the TaxAmount value will be returned as a monthly figure.
        Returns:
        float Calculated tax amount
        Throws:
        TaxControlException - for errors encountered when computing the tax, or if DataFilename or SelectedTax is invalid.
        See Also:
        setPayPeriodsPerYear(int)
      • getTaxableWages

        public float getTaxableWages()
                              throws TaxControlException
        Returns the taxable wages. For most taxes, the all of the Earnings are taxable. If, however, there is an applicable wage limit, the taxable amount may be smaller.
        Returns:
        float taxable wages
        Throws:
        TaxControlException - for errors encountered during computation, or if DataFilename or SelectedTax is invalid.
        See Also:
        getEarnings()
      • getTaxBracket

        public float getTaxBracket()
                            throws TaxControlException
        Returns the calculated tax bracket. This method returns the tax bracket of the employee's computed tax, expressed as a float value (independent of PayPeriodsPerYear).
        Returns:
        float Calculated tax bracket
        Throws:
        TaxControlException - for errors encountered when computing the tax, or if DataFilename or SelectedTax is invalid.
      • setAuxiliary

        public void setAuxiliary​(float auxiliary)
        Sets the "Auxiliary" value, which is used for state and local tax special data needs. The computation of some state or local taxes requires special information not used by the majority of calculations. In these taxes the Auxiliary property is used for storage of the required information. The specific usage, if any, is detailed in the Instructions property for the tax requiring this information. The Miscellaneous property is used in the same manner. However, usage of Auxiliary is much less common than Miscellaneous.
        Parameters:
        auxiliary - Amount to which auxiliary should be set.
        See Also:
        setAuxiliary(float), setMiscellaneous(float), getInstructions()
      • getAuxiliary

        public float getAuxiliary()
        Gets the "Auxiliary" value. The computation of some state or local taxes requires special information not used by the majority of calculations. In these taxes the Auxiliary property is used for storage of the required information. The specific usage, if any, is detailed in the Instructions property for the tax requiring this information. The Miscellaneous property is used in the same manner. However, usage of Auxiliary is much less common than Miscellaneous.
        Returns:
        float value of "Auxiliary"
        See Also:
        setMiscellaneous(float)
      • showAboutBox

        public void showAboutBox()
        Show the control's About box.
      • setAutoUnlock

        public void setAutoUnlock​(boolean autoUnlock)
        Indicates whether or not the control should prompt before attempting to unlock a new Tax Table file.
        Parameters:
        autoUnlock - setting
      • isAutoUnlock

        public boolean isAutoUnlock()
        Indicates whether or not the control should prompt before attempting to unlock a new Tax Table file.
        Returns:
        boolean AutoUnlock setting
      • setDataFilename

        public void setDataFilename​(java.lang.String dataFilename)
        Indicates the Tax Table file name. All tax table data is provided in a separate data file (typically "us.dat"), which is updated as needed. It is essential that the DataFilename property points to this file. If the data file is located in the working directory, only the filename and extension are required for dataFilename. Otherwise the path and filename plus extension must be provided.
        Parameters:
        dataFilename - String path to tax data file
      • getDataFilename

        public java.lang.String getDataFilename()
        Indicates the Tax Table file name. All tax table data is provided in a separate data file (typically "us.dat"), which is updated as needed. It is essential that the DataFilename property points to this file. If the data file is located in the working directory, only the filename and extension are required for dataFilename. Otherwise the path and filename plus extension must be provided.
        Returns:
        String filename
      • setEarnings

        public void setEarnings​(float earnings)
        Sets employee's taxable earnings. This property provides the employee's current earnings to be taxed, expressed in terms of the pay period established by the PayPeriodsPerYear property. In other words, if PayPeriodsPerYear is set to 12, the Earnings value will be interpreted as a monthly figure for tax calculation purposes. If PayPeriodsPerYear is 52, Earnings will be interpreted as weekly.
        Parameters:
        earnings - float for current period
        See Also:
        setPayPeriodsPerYear(int), setYTDEarnings(float)
      • getEarnings

        public float getEarnings()
        Gets employee's earnings setting. This property provides the employee's current earnings to be taxed, expressed in terms of the pay period established by the PayPeriodsPerYear property. In other words, if PayPeriodsPerYear is set to 12, the Earnings value will be interpreted as a monthly figure for tax calculation purposes. If PayPeriodsPerYear is 52, Earnings will be interpreted as weekly.
        Returns:
        float value of employee's current earnings
        See Also:
        setPayPeriodsPerYear(int), setYTDEarnings(float)
      • setExemptions

        public void setExemptions​(int exemptions)
        Sets employee's Federal exemptions. This input property indicates the employee's exemptions, taken from federal form W-4, line 5. This value is used by the federal income tax (FIT), as well as many state taxes. For states which use this value for exemptions, the StateExemptions property may be left blank. For states which use an exemption level different from federal, place that value in the StateExemptions property.
        Parameters:
        exemptions - Number of exemption to be applied
        See Also:
        setStateExemptions(int)
      • getExemptions

        public int getExemptions()
        Gets employee's Federal exemptions. This input property indicates the employee's exemptions, taken from federal form W-4, line 5. This value is used by the federal income tax (FIT), as well as many state taxes. For states which use this value for exemptions, the StateExemptions property may be left blank. For states which use an exemption level different from federal, place that value in the StateExemptions property.
        Returns:
        int value of employee's exemptions
        See Also:
        getStateExemptions()
      • setFilingStatus

        public void setFilingStatus​(int filingStatus)
                             throws TaxControlException
        Sets filing status of employee. See getFilingStatus() for possible values.
        Parameters:
        filingStatus - Employee's filing status
        Throws:
        TaxControlException - when passed an invalid filingstatus value.
        See Also:
        FilingStatus
      • getFilingStatus

        public int getFilingStatus()
        Retrieves filing status of employee. Possible values are:
        • FilingSingle = 0
        • FilingHeadOfHousehold = 1
        • FilingWidow = 2
        • FilingMarried = 3
        • FilingSeparate = 4
        • FilingBothEmployed = 5
        Returns:
        FilingStatus of employee
        See Also:
        FilingStatus
      • setStateFilingStatus

        public void setStateFilingStatus​(int filingStatus)
                                  throws TaxControlException
        Sets filing status of employee for state withholding. See getFilingStatus() for possible values.
        Parameters:
        filingStatus - Employee's filing status
        Throws:
        TaxControlException - when passed an invalid filingstatus value.
        See Also:
        FilingStatus
      • getStateFilingStatus

        public int getStateFilingStatus()
        Retrieves filing status of employee for state withholding. Default value is FilingStatus value.
        Returns:
        int StateFilingStatus of employee
        See Also:
        FilingStatus
      • getInstructions

        public java.lang.String getInstructions()
                                         throws TaxControlException
        Instructions which correspond to the selected tax (read-only). A tax is first selected with the SelectedTax Property. Any special instructions for that tax are then made available through both the Instructions and XMLInstructions properties. These instructions generally involve the usage of the various fields (especially the Miscellaneous and Auxiliary properties) for this particular tax.
        Returns:
        String instructions.
        Throws:
        TaxControlException - if DataFilename or SelectedTax is invalid.
      • getXMLInstructions

        public java.lang.String getXMLInstructions()
                                            throws TaxControlException
        XML-formatted Instructions which correspond to the selected tax (read-only). A tax is first selected with the SelectedTax Property. Any special instructions for that tax are then made available through both the Instructions and XMLInstructions properties. These instructions generally involve the usage of the various fields (especially the Miscellaneous and Auxiliary properties) for this particular tax.
        Returns:
        String instructions.
        Throws:
        TaxControlException - if DataFilename or SelectedTax is invalid.
      • isTableCurrent

        public boolean isTableCurrent()
                               throws java.io.IOException,
                                      TaxControlException
        Returns True if the Tax Table named in the DataFilename property is current. An application may test the local Tax Table file, to see if is it current, using the IsTableCurrent Property. If the local PC has Internet access, the control will query the Caliber Technology Inc. web site, comparing the local Tax Table's version with that of the most recent table on the web site. Returns True if the versions match, False otherwise. The application may then automatically download the new table using the downloadTable method. Internet Access is required to use this property.

        Returns:
        boolean True if tax table is up to date
        Throws:
        java.io.IOException - Thrown if Internet access fails.
        TaxControlException - if there's a problem with the tax table file.
        See Also:
        downloadTable(java.lang.String, java.lang.String, boolean)
      • setMiscellaneous

        public void setMiscellaneous​(float miscellaneous)
        Sets the "Miscellaneous" value, used for state and local tax special data needs. The computation of some state or local taxes requires special information fields. In these taxes the Miscellaneous property is used for storage of the required information. The specific usage, if any, is detailed in the Instructions properties for the tax requiring this information. The Auxiliary property is used in the same manner. However, usage of Auxiliary is much less common in the tax formulae than Miscellaneous.
        Parameters:
        miscellaneous - value
        See Also:
        setAuxiliary(float)
      • getMiscellaneous

        public float getMiscellaneous()
        Gets the "Miscellaneous" value, used for state and local tax special data needs. The computation of some state or local taxes requires special information fields. In these taxes the Miscellaneous property is used for storage of the required information. The specific usage, if any, is detailed in the Instructions properties for the tax requiring this information. The Auxiliary property is used in the same manner. However, usage of Auxiliary is much less common in the tax formulae than Miscellaneous.
        Returns:
        float Miscellaneous value
        See Also:
        getAuxiliary()
      • getYTDTax

        public float getYTDTax()
        Gets the Amount of tax paid year-to-date, not including the current pay period.
        Returns:
        float YTDTax value
      • setYTDTax

        public void setYTDTax​(float YTDTax)
        Used to indicate year-to-date tax amount paid previous to current pay period.
        Parameters:
        YTDTax - The amount of tax paid year-to-date before current period.
        See Also:
        getYTDTax()
      • setYTDTax

        public void setYTDTax​(double YTDTax)
        Sets the year-to-date tax paid.
        See Also:
        setYTDTax(float)
      • setPayPeriodsPerYear

        public void setPayPeriodsPerYear​(int payPeriodsPerYear)
        Parameters:
        payPeriodsPerYear - The number of pay periods in a year
        See Also:
        getPayPeriodsPerYear()
      • getPayPeriodsPerYear

        public int getPayPeriodsPerYear()
        The number of pay periods in a year. This property numerically defines the pay period to be used in calculations. This value defaults to 12, which corresponds to a monthly pay period. The Earnings property and the TaxAmount method are expressed in terms of this same pay period.

        For example, suppose we have

        PayPeriodsPerYear = 12
        Earnings = 1000

        giving a TaxAmount of $150. The Earnings and TaxAmount are both monthly figures.

        If we were to set

        PayPeriodsPerYear = 24

        the $1000 Earnings value would now correspond to a semi-monthly figure, and TaxAmount would produce a new semi-monthly tax figure, in all likelihood not $150. (This is because most taxes are based on brackets which determine the tax rate.)

        Returns:
        The number of pay periods in a year
      • getPublished

        public java.lang.String getPublished()
                                      throws TaxControlException
        Publication information for the selected tax (read-only). The Published property provides the user with a string identifying the tax code publication used for the currently selected tax. The tax may be selected using the SelectedTax or Text or ListIndex Property. A similar field, the Version property, indicates version information for the entire Tax Table data file.
        Returns:
        String Published property
        Throws:
        TaxControlException - if DataFilename or SelectedTax is invalid.
        See Also:
        Taxes.getVersion()
      • getPayDate

        public java.util.Date getPayDate()
        Date on the paycheck. This can affect which formula is used, if there are more than one. The PayDate is compared to each formula's EffectiveDate to determine which one applies.
        Returns:
        java.util.Date PayDate property
      • getSoftwareVersion

        public java.lang.String getSoftwareVersion()
        TaxControls software version.
        Returns:
        String Version of this software.
      • isRoundingRequired

        public boolean isRoundingRequired()
                                   throws TaxControlException
        Indicates whether the selected tax has been rounded to the nearest dollar amount (read-only). A tax is selected using the SelectedTax Property. If the selected tax has been rounded to the nearest dollar amount, the value returned by this property will be True (non-zero). Otherwise, the value returned is False (zero).
        Returns:
        boolean RoundingRequired property
        Throws:
        TaxControlException - if DataFilename or SelectedTax is invalid.
      • isRoundingOptional

        public boolean isRoundingOptional()
                                   throws TaxControlException
        Indicates whether the selected tax can been rounded to the nearest dollar amount (read-only). A tax is selected using the SelectedTax Property. If the selected tax may be rounded to the nearest dollar amount, the value returned by this property will be True (non-zero). Otherwise, the value returned is False (zero).
        Returns:
        boolean RoundingOptional property
        Throws:
        TaxControlException - if DataFilename or SelectedTax is invalid.
      • isDiscontinued

        public boolean isDiscontinued()
                               throws TaxControlException
        Indicates whether the selected tax has been discontinue. A tax is selected using the SelectedTax Property. If the selected tax is discontinued, the value returned by this property will be True (non-zero). Otherwise, the value returned is False (zero).
        Returns:
        boolean Discontinued property
        Throws:
        TaxControlException - if DataFilename or SelectedTax is invalid.
      • isWithheldTax

        public boolean isWithheldTax()
                              throws TaxControlException
        Indicates whether the selected tax has should be withheld from the employee's pay.
        Returns:
        boolean True if employee pays, false if employer pays.
        Throws:
        TaxControlException - if DataFilename or SelectedTax is invalid.
      • setRoundWhenOptional

        public void setRoundWhenOptional​(boolean round)
        Sets the value of RoundWhenOptional field. If true, all taxes which may be rounded are rounded.
        Parameters:
        round - boolean - should taxes be rounded when permitted?
      • isRoundWhenOptional

        public boolean isRoundWhenOptional()
        Returns value of RoundWhenOption field. If true, all taxes which may be rounded are rounded.
        Returns:
        boolean - should taxes be rounded when permitted?
      • setSelectedTax

        public void setSelectedTax​(java.lang.String selectedTax)
        Sets the tax for computation.
        Parameters:
        selectedTax - Name of tax selected for computation.
        See Also:
        getSelectedTax()
      • getSelectedTax

        public java.lang.String getSelectedTax()
        Gets the tax for computation. The SelectedTax property is used to select the tax to be used in subsequent calculations. For example,
        TaxControl oTax = new TaxControl();
        oTax.setDataFilename("us.dat");
        oTax.setSelectedTax("FIT");
        Setting the value to a nonexistent tax will cause a TaxControlException to be thrown when the calculation is performed by getTaxAmount().
        Returns:
        String Tax selected for computation.
      • setStateExemptions

        public void setStateExemptions​(int stateExemptions)
        Sets employee's state exemptions.
        Parameters:
        stateExemptions - The number of State exemptions.
        See Also:
        getStateExemptions(), setMiscellaneous(float)
      • getStateExemptions

        public int getStateExemptions()
        Returns employee's state exemptions. This input property indicates the employee's exemptions, taken from various state forms (indicated by the Instructions properties). This value is used by many state taxes. For states which use an exemption level different from federal, place that value in the StateExemptions property.

        Note: California uses both State Exemptions and Additional Exemptions. As indicated in the Instructions, the Miscellaneous property should be set to the Additional Exemptions amount. Georgia also uses Additional Exemptions, but the tables do not require a separate entry for these, so the StateExemptions field for Georgia may contain the total of regular plus additional exemptions.
        Returns:
        int Number of State exemptions.
        See Also:
        getMiscellaneous()
      • setSupplemental

        public void setSupplemental​(boolean supplemental)
        Sets "Supplemental" property, which indicates whether the Earnings property contains supplemental earnings.
        Parameters:
        supplemental - Flag which indicates whether earnings should be taxed as supplemental
        See Also:
        setEarnings(float)
      • isSupplemental

        public boolean isSupplemental()
        Returns "Supplemental" property, which indicates whether the Earnings property contains supplemental earnings. Supplemental earnings (for example, a bonus), may be taxed at a special rate.
        This input property denotes whether the employee's current earnings should be taxed as regular wages or as supplemental wages. For some taxes, the supplemental rate is different from regular withholding rates. The Instructions property for these taxes indicates that a special supplemental rate is used.
        Returns:
        boolean True if earnings should be taxed as supplemental
      • getTaxType

        public java.lang.String getTaxType()
                                    throws TaxControlException
        Retrieves type of the currently selected tax. Possible values are:
        • F - Federal. Federal income and FICA-related taxes.
        • S - State. State income taxes.
        • L - Local. Local income taxes.
        • O - Other. Other taxes, such as unemployment and disability.
        • P - Private. Used internally by TaxControls for computations.
        Returns:
        String representing type of the currently selected tax.
        Throws:
        TaxControlException - if DataFilename or SelectedTax is invalid.
        See Also:
        setSelectedTax(java.lang.String)
      • setYTDEarnings

        public void setYTDEarnings​(float YTDEarnings)
        Used to indicate year-to-date amounts earned previous to current earnings. Some tax calculations involve annual caps in determining the TaxAmount. In order for these caps to be applied correctly, all previous earnings (i.e., earned before the amount indicated in the Earnings property) should be entered here. Each tax which uses this information is noted as such in its Instructions and XMLInstructions properties.

        As an example, suppose an employee with a biweekly pay period earns $4000 and you would like to compute FICA for the period. If previous earnings are $63,000, and filing status is Single, you would set the following properties:

        PropertyValueComments
        PayPeriodsPerYear26Corresponds to a biweekly pay period.
        FilingStatus00 - FilingSingle (Single status)
        Earnings4000$4000 salary for the pay period.
        YTDEarnings63000$63,000 was earned this year prior to the current pay period.


        This employee's earnings have surpassed the Social Security annual cap (for this example from a previous year, $65,400), so the TaxAmount computation will apply FICA Med percentage to the entire Earnings amount, and FICA SS percentage only on the first $2400 ($65,400 - $63,000) of the Earnings.
        Parameters:
        YTDEarnings - The amount earned year-to-date before current period.
        See Also:
        setEarnings(float)
      • setYTDEarnings

        public void setYTDEarnings​(double YTDEarnings)
        Sets the year-to-date amount of earnings.
        See Also:
        setYTDEarnings(float)
      • getYTDEarnings

        public float getYTDEarnings()
        Used to indicate year-to-date amounts earned previous to current earnings. Some tax calculations involve annual caps in determining the TaxAmount. In order for these caps to be applied correctly, all previous earnings (i.e., earned before the amount indicated in the Earnings property) should be entered here. Each tax which uses this information is noted as such in its Instructions and XMLInstructions properties.

        As an example, suppose an employee with a biweekly pay period earns $4000 and you would like to compute FICA for the period. If previous earnings are $63,000, and filing status is Single, you would set the following properties:

        PropertyValueComments
        PayPeriodsPerYear26Corresponds to a biweekly pay period.
        FilingStatus00 - FilingSingle (Single status)
        Earnings4000$4000 salary for the pay period.
        YTDEarnings63000$63,000 was earned this year prior to the current pay period.


        This employee's earnings have surpassed the Social Security annual cap (for this example from a previous year, $65,400), so the TaxAmount computation will apply FICA Med percentage to the entire Earnings amount, and FICA SS percentage only on the first $2400 ($65,400 - $63,000) of the Earnings.
        Returns:
        float The amount earned year-to-date before current period.
        See Also:
        getEarnings()
      • setUnemploymentRate

        public void setUnemploymentRate​(double rate)
        Sets the rate to be used for unemployment tax calculations. This is the company's unemployment rate, which is generally changed each year, and is issued by the state where the main workplace is located.
        Parameters:
        rate - A floating point value. For example, use .05 for a 5% rate
      • setUnemploymentRate

        public void setUnemploymentRate​(float rate)
        Sets the rate to be used for unemployment tax calculations.
        Parameters:
        rate - A floating point value. For example, use .05 for a 5% rate
        See Also:
        setUnemploymentRate(double)
      • getUnemploymentRate

        public float getUnemploymentRate()
        Gets the rate to be used for unemployment tax calculations.
        See Also:
        setUnemploymentRate(double)
      • getWebServiceAddress

        public java.lang.String getWebServiceAddress()
        Returns the TaxQuery web service url.
      • setWebServiceAddress

        public void setWebServiceAddress​(java.lang.String url)
        Sets the TaxQuery web service url. Defaults to Caliber Technology supplied web service.
      • getJSONStatus

        public static java.lang.String getJSONStatus​(java.lang.String json)
      • getJSONError

        public static java.lang.String getJSONError​(java.lang.String json)
      • getJSONString

        public static java.lang.String getJSONString​(java.lang.String name,
                                                     java.lang.String json)
      • getJSONArray

        public static java.lang.String[] getJSONArray​(java.lang.String json)
      • getTaxQuery

        public java.lang.String getTaxQuery​(java.lang.String workAddress,
                                            java.lang.String homeAddress)
                                     throws TaxControlException
        Returns a comma-delimited String containing suggested State, Local and Other (usually Unemployment) taxes applicable to work and residence addresses. Accesses the TaxQuery web service, requiring Docker instance running the service. You should set the network address of the web service using setWebServiceAddress(). This function is obsolete, due to a new TaxQuery webservice API. The only getTaxQuery parameters are now work address and home address.
        Parameters:
        workAddress - String Workplace address
        homeAddress - String Home address
        Returns:
        String Comma-delimited String of tax names.
        Throws:
        TaxControlException - if web service returns an error.
        See Also:
        getTaxNamesForZip(int, int), setWebServiceAddress(java.lang.String)
      • getTaxQuery

        public java.lang.String getTaxQuery​(java.lang.String workAddress,
                                            java.lang.String homeAddress,
                                            java.lang.String nexus)
                                     throws TaxControlException
        Throws:
        TaxControlException
      • getTaxQuery

        public java.lang.String getTaxQuery​(int zipwork,
                                            java.lang.String streetwork,
                                            int numwork,
                                            int ziphome,
                                            java.lang.String streethome,
                                            int numhome,
                                            java.lang.String username,
                                            java.lang.String password)
                                     throws TaxControlException
        Returns a comma-delimited String containing suggested State, Local and Other (usually Unemployment) taxes applicable to work and residence addresses. Accesses the TaxQuery web service, requiring an internet connection. This function is obsolete, due to a new TaxQuery webservice API. The only getTaxQuery parameters are now work address and home address.
        Parameters:
        zipwork - int Workplace zip code.
        streetwork - String Workplace street name.
        numwork - int Workplace addresses number.
        ziphome - int Home zip code.
        streethome - String Home street name.
        numhome - int Home addresses number.
        username - String TaxQuery web service username, available from Caliber Technology LLC (http://taxupdate.com).
        password - String TaxQuery web service password.
        Returns:
        String Comma-delimited String of tax names.
        Throws:
        TaxControlException - if web service returns an error.
        See Also:
        getTaxNamesForZip(int, int), getStreetQuery(int, java.lang.String, java.lang.String, java.lang.String)
      • getStreetQuery

        public java.lang.String getStreetQuery​(int zip,
                                               java.lang.String search,
                                               java.lang.String username,
                                               java.lang.String password)
                                        throws TaxControlException
        Returns a newline and comma-delimited String containing suggested street name matches within a ZIP Code. Accesses the StreetQuery web service, requiring an internet connection. This function is obsolete, due to a new TaxQuery webservice API. Street query is no longer available.
        Parameters:
        zip - int zip code to search
        search - String containing partial match, or blank for all street names
        username - String TaxQuery web service username, available from Caliber Technology LLC (http://taxupdate.com).
        password - String TaxQuery web service password.
        Returns:
        String Three lines of Comma-delimited street names: first line is Soundex matches, second is street names starting with 'search' param, third is street names containing (but not starting with) 'search' param.
        Throws:
        TaxControlException - if web service returns an error.
        See Also:
        getTaxNamesForZip(int, int), getTaxQuery(java.lang.String, java.lang.String)