README.textile

   1 h1. Fiscal-Year "!https://secure.travis-ci.org/sebhoss/fiscal-year.png!":http://travis-ci.org/sebhoss/fiscal-year "!https://www.ohloh.net/p/fiscal-year/widgets/project_thin_badge.gif!":https://www.ohloh.net/p/fiscal-year/
   2
   3 p. Your company doesn't work from January 1 to December 31? Try fiscal-year, a small Java library which converts calendar-year based dates to corresponding dates in a "fiscal year":http://en.wikipedia.org/wiki/Fiscal_year.
   4
   5 h2. Usage
   6
   7 p. First create a @FiscalYearFactory@ which holds the configuration of your company's fiscal year:
   8
   9 bc. // fiscal year starts at month 11 of the 'previous' year
  10 FiscalYearFactory earlyYearFactory = FiscalYears.earlyFiscalYear(11);
  11 // fiscal year starts at month 3 in the 'current' year
  12 FiscalYearFactory lateYearFactory = FiscalYears.lateFiscalYear(3);
  13
  14 p. Then use this factory to convert a calendar-year based @LocalDate@ to a corresponding @FiscalDate@:
  15
  16 bc. LocalDate calendarDate = LocalDate.now();
  17 FiscalDate fiscalDate = factory.create(calendarDate);
  18
  19 p. Query the newly created @FiscalDate@ to retrieve the usual suspects of attributes:
  20
  21 bc.. fiscalDate.getFiscalYear();
  22 fiscalDate.getFiscalMonth();
  23 fiscalDate.getFiscalDayOfYear();
  24 fiscalDate.getFiscalWeekOfYear();
  25
  26 fiscalDate.getCalendarYear();
  27 fiscalDate.getCalendarMonth();
  28 fiscalDate.getCalendarDayOfMonth();
  29 fiscalDate.getCalendarDayOfYear();
  30 fiscalDate.getCalendarWeekOfWeekyear();
  31
  32 p. Do some math with dates as follows:
  33
  34 bc. fiscalDate.plusYears(years);
  35 fiscalDate.plusMonths(months);
  36 fiscalDate.plusWeeks(int weeks);
  37 fiscalDate.plusDays(int days);
  38 fiscalDate.minusYears(int years);
  39 fiscalDate.minusMonths(int months);
  40 fiscalDate.minusWeeks(int weeks);
  41 fiscalDate.minusDays(int days);
  42
  43 p. Or finally convert it back to a @LocalDate@:
  44
  45 bc. LocalDate calendarDate = fiscalDate.asLocalDate();
  46
  47 p. All classes are immutable and therefore thread-safe. The library currently relies on "Joda Time":http://joda-time.sourceforge.net/ but will be updated to use the new "JSR 310":http://jcp.org/en/jsr/detail?id=310 based Date API.
  48
  49 h2. Integration
  50
  51 bc.
  52 <dependency>
  53   <groupId>com.github.sebhoss</groupId>
  54   <artifactId>fiscal-year</artifactId>
  55   <version>1.0.0</version>
  56 </dependency>
  57
  58
  59 h2. Development
  60
  61 h3. License
  62
  63 p. This program is free software. It comes without any warranty, to the extent permitted by applicable law. You can redistribute it and/or modify it under the terms of the Do What The Fuck You Want To Public License, Version 2, as published by Sam Hocevar. See LICENSE or "http://www.wtfpl.net/":http://www.wtfpl.net/ for more details.
  64
  65 h3. Setup
  66
  67 p. This projects uses "Java":http://www.java.com/, "Maven":http://maven.apache.org/ and "Git":http://git-scm.com/ as the main development tools. To build the project yourself just download & install at least Maven 3.0 and call *mvn install* inside the project folder. Maven should then proceed to clean, build, package and install this project.
  68
  69 h3. Versioning
  70
  71 p. This project follows the "semantic versioning":http://semver.org/ guidelines.