README

   1 ========================\r
   2  iCal4j - Release Notes\r
   3 ========================\r
   4 \r
   5  - For a concise description of the goals and directions of iCal4j please\r
   6  take a look at docs/index.html.\r
   7 \r
   8  - You will find examples of how to use iCal4j at docs/introduction.html\r
   9  and throughout the API documentation.\r
  10 \r
  11  - Detailed descriptions of changes included in each release may be found\r
  12  in the CHANGELOG.\r
  13  \r
  14  - iCal4j was created with the help of eclipse version 3.2 [http://eclipse.org].\r
  15  Note that the project metadata included in the source version of iCal4j may not\r
  16  be compatible with prior versions of eclipse.\r
  17 \r
  18 \r
  19 =====================\r
  20  System Requirements\r
  21 =====================\r
  22 \r
  23  - Java 1.4.2 or later\r
  24  \r
  25  - commons-codec 1.3\r
  26  \r
  27  - commons-lang 2.1\r
  28  \r
  29  - commons-logging 1.1\r
  30  \r
  31  - junit 3.8.2 (for unit testing only)\r
  32  \r
  33 \r
  34 =======================\r
  35  How to build - Maven2\r
  36 =======================\r
  37 \r
  38  After installing Maven2 and adding to your path, you need to modify your local\r
  39  profiles http://wiki.modularity.net.au/ical4j/index.php?title=Maven2. Then \r
  40  open a command prompt to the location of the iCal4j source and execute the following:\r
  41  \r
  42   [iCal4j-1.0-beta1-src] >mvn clean install\r
  43   or\r
  44   [iCal4j-1.0-beta1-src] >mvn clean install -P modularity-snapshots\r
  45  \r
  46  This will build and install iCal4j in your local repository. Build artifacts\r
  47  are generated in the 'target' directory.\r
  48 \r
  49 \r
  50 ====================\r
  51  How to build - Ant\r
  52 ====================\r
  53  \r
  54  If you have downloaded the source distribution, you should be able to package a JAR\r
  55  file simply by running ant in the root directory. e.g:\r
  56  \r
  57    C:\Libs\iCal4j-1.0-beta1-src\>ant\r
  58  \r
  59  If for some reason you would like to override the default build classpath, I would\r
  60  suggest creating a "build.properties" file (see the provided sample) in the root directory\r
  61  and add overridden properties to this. You can also override properties via Java system\r
  62  properties (e.g. -Dproject.classpath="..."). You shouldn't need to modify the "build.xml" at all,\r
  63  so if you do find a need let me know and I'll try to rectify this.\r
  64  \r
  65  \r
  66  \r
  67 =================\r
  68  Relaxed Parsing\r
  69 =================\r
  70 \r
  71  iCal4j now has the capability to "relax" its parsing rules to enable parsing of\r
  72  *.ics files that don't properly conform to the iCalendar specification (RFC2445)\r
  73  \r
  74  - You can relax iCal4j's unfolding rules by specifying the following system property:\r
  75  \r
  76     ical4j.unfolding.relaxed=true\r
  77  \r
  78  Note that I believe this problem is not restricted to Mozilla calendaring\r
  79  products, but rather may be caused by UNIX/Linux-based applications relying on the\r
  80  default newline character (LF) to fold long lines (KOrganizer also seems to have this\r
  81  problem). This is, however, still incorrect as by definition long lines are folded\r
  82  using a (CRLF) combination.\r
  83  \r
  84  I've obtained a couple of samples of non-standard iCalendar files that I've included\r
  85  in the latest release (0.9.11). There is a Sunbird, phpicalendar, and a KOrganizer\r
  86  sample there (open them in Notepad on Windows to see what I mean).\r
  87 \r
  88  It seems that phpicalendar and KOrganizer always use LF instead of CRLF, and in\r
  89  addition KOrganizer seems to fold all property parameters and values (similar to\r
  90  Mozilla Calendar/Sunbird).\r
  91 \r
  92  Mozilla Calendar/Sunbird uses CRLF to fold all property parameter/values, however it\r
  93  uses just LF to fold long lines (i.e. longer than 75 characters).\r
  94 \r
  95  The latest release of iCal4j includes changes to UnfoldingReader that should work\r
  96  correctly with Mozilla Calendar/Sunbird, as long as the ical4j.unfolding.relaxed\r
  97  system property is set to true.\r
  98 \r
  99  KOrganizer/phpicalendar files should also work with the relaxed property, although\r
 100  because ALL lines are separated with just LF it also relies on the StreamTokenizer to\r
 101  correctly identify LF as a newline on Windows, and CRLF as a newline on UNIX/Linux. The\r
 102  API documentation for Java 1.5 says that it does do this, so if you still see problems\r
 103  with parsing it could be a bug in the Java implementation.\r
 104  \r
 105  \r
 106  - You may also relax the parsing rules of iCal4j by setting the following system property:\r
 107  \r
 108      ical4j.parsing.relaxed=true\r
 109  \r
 110  This property is intended as a general relaxation of parsing rules to allow for parsing\r
 111  otherwise invalid calendar files. Initially enabling this property will allow for the\r
 112  creation of properties and components with illegal names (e.g. Mozilla Calendar's "X"\r
 113  property). Note that although this will allow for parsing calendars with illegal names,\r
 114  validation will still identify such names as an error in the calendar model.\r
 115 \r
 116 \r
 117  - Microsoft Outlook also appears to provide quoted TZID parameter values, as follows:\r
 118  \r
 119    DTSTART;TZID="Pacific Time (US & Canada),Tijuana":20041011T223000\r
 120  \r
 121  To allow for compatibility with such iCalendar files you should specify the\r
 122  following system property:\r
 123  \r
 124    ical4j.compatibility.outlook=true\r
 125  \r
 126  The full set of system properties may be found in\r
 127  net.fortuna.ical4j.util.CompatibilityHints.\r
 128 \r
 129 \r
 130 ======================\r
 131  iCal4j and Timezones\r
 132 ======================\r
 133 \r
 134  Supporting timezones in an iCalendar implementation can be a complicated process,\r
 135  mostly due to the fact that there is not a definitive list of timezone definitions\r
 136  used by all iCalendar implementations. This means that an iCalendar file may be\r
 137  produced by one implementation and, if the file does not include all definitions\r
 138  for timezones relevant to the calendar properties, an alternate implementation\r
 139  may not know how to interpret the timezone identified in the calendar (or worse,\r
 140  it may interpret the timezone differently to the original implementation). All\r
 141  of these possibilities mean unpredictable behaviour which, to put it nicely, is\r
 142  not desireable.\r
 143  \r
 144  iCal4j approaches the problem of timezones in two ways: The first and by far the\r
 145  preferred approach is for iCalendar files to include definitions for all timezones\r
 146  referenced in the calendar object. To support this, when an existing calendar is\r
 147  parsed a list of VTimeZone definitions contained in the calendar is constructed.\r
 148  This list may then be queried whenever a VTimeZone definition is required.\r
 149  \r
 150  The second approach is to rely on a registry of VTimeZone definitions. iCal4j\r
 151  includes a default registry of timezone definitions (derived from the Olson timezone\r
 152  database - a defacto standard for timezone definitions), or you may also provide your\r
 153  own registry implementation from which to retreieve timezones. This approach is\r
 154  required when constructing new iCalendar files.\r
 155  \r
 156  Note that the intention of the iCal4j model is not to provide continuous validation\r
 157  feedback for every change in the model. For this reason you are free to change\r
 158  timezones on Time objects, remove or add TzId parameters, remove or add VTimeZone\r
 159  definitions, etc. without restriction. However when validation is run (automatically\r
 160  on output of the calendar) you will be notified if the changes are invalid.\r
 161  \r
 162 \r
 163 ============================\r
 164  Pre-Java 1.4 Compatibility\r
 165 ============================\r
 166 \r
 167  Choosing Java 1.4 as the minimum required JVM was initially slightly arbitrary, and\r
 168  probably based on the fact that most people were using 1.4 as a minimum.\r
 169 \r
 170  Since then, however, there are two features of 1.4 I can think of that iCal4j requires:\r
 171         - the URI class;\r
 172         - and the java.util.regex.* package (used in StringUtils).\r
 173 \r
 174  If you don't think you will be needing these features in your own code, you may want to\r
 175  try compiling iCal4j with JDK 1.4 using the "-target 1.3" option but without specifying\r
 176  an alternative "-bootclasspath" option. From what I can tell, this should generate 1.3\r
 177  bytecode that you can run on a 1.3 JVM. Note however, that if your code does cause\r
 178  iCal4j to load the URI or java.util.regex.* references then it will fail on a 1.3 JVM\r
 179  (as these APIs aren't available).\r
 180 \r
 181  \r
 182 =================\r
 183  Redistribution:\r
 184 =================\r
 185 \r
 186 If you intend to use and distribute iCal4j in your own project please\r
 187 follow these very simple guidelines:\r
 188  \r
 189  - Make a copy of the LICENSE, rename it to LICENSE.iCal4j, and save\r
 190  it to the directory where you are re-distributing the iCal4j JAR.\r
 191  \r
 192  - I don't recommend extracting the iCal4j classes from its JAR and package\r
 193  in another JAR along with other classes. It may lead to version incompatibilites\r
 194  in the future. Rather I would suggest to include the ical4j.jar in your classpath\r
 195  as required.\r