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.createFromCalendarDate(calendarDate);
  18
  19 p. Use fiscal-year based values directly to create an instance of @FiscalDate@:
  20
  21 bc. FiscalDate fiscalDate = factory.create(2015, 3, 25);
  22
  23 p. Query the newly created @FiscalDate@ to retrieve the usual suspects of attributes:
  24
  25 bc.. fiscalDate.getFiscalYear();
  26 fiscalDate.getFiscalMonth();
  27 fiscalDate.getFiscalDayOfYear();
  28 fiscalDate.getFiscalWeekOfYear();
  29
  30 fiscalDate.getCalendarYear();
  31 fiscalDate.getCalendarMonth();
  32 fiscalDate.getCalendarDayOfMonth();
  33 fiscalDate.getCalendarDayOfYear();
  34 fiscalDate.getCalendarWeekOfWeekyear();
  35
  36 p. Do some math with dates as follows:
  37
  38 bc. fiscalDate.plusYears(years);
  39 fiscalDate.plusMonths(months);
  40 fiscalDate.plusWeeks(int weeks);
  41 fiscalDate.plusDays(int days);
  42 fiscalDate.minusYears(int years);
  43 fiscalDate.minusMonths(int months);
  44 fiscalDate.minusWeeks(int weeks);
  45 fiscalDate.minusDays(int days);
  46
  47 p. Or finally convert it back to a @LocalDate@:
  48
  49 bc. LocalDate calendarDate = fiscalDate.asLocalDate();
  50
  51 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 once it is released.
  52
  53 h2. Integration
  54
  55 bc.
  56 <dependency>
  57   <groupId>com.github.sebhoss</groupId>
  58   <artifactId>fiscal-year</artifactId>
  59   <version>[1.0.1,2.0.0)</version>
  60 </dependency>
  61
  62
  63 h2. Development
  64
  65 h3. License
  66
  67 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.
  68
  69 h3. Setup
  70
  71 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.
  72
  73 h3. Versioning
  74
  75 p. This project follows the "semantic versioning":http://semver.org/ guidelines.