restrictions.txt

Restrictions
------------
 
Basically the language features of java 8 are provided with the following restrictions
(which will be enforced by the converter at compile time):
 
- Threads   
    No threading is supported at all. No synchronization keywords either.   
      
- Exceptions
    While exceptions are largely supported, it is not possible to use a catch-clause
    for any RuntimeException (all exceptions that need not be declared in the method
    signature).
    You can also not catch any super-class of these, like Exception or Throwable.
    But you can and should throw such exceptions to signify program errors.
      
    The only exception to this rule is the NumberFormatException which may actually 
    be caught because there is no real way for a program to prevent
    this exception to happen on unknown input data (as in contrast to NullPointerException, etc.)
      
- No reflection and no type annotations
    Runtime type information is basically completely removed. Only the use of 'instanceof'
    and of checked cast operations (throwing ClassCastException in case of faults) are provided.
    For compatibility the compiler accepts (but ignores) annotations in the code
    (like @Override and @SuppressWarnings).    
      
- no 'long' and no 'float'
    These data types are impossible to implement correctly in javascript, since it
    only supports a single Number type. This type is identical to a java double and
    can also be used to hold all integer values up to the size of int. A "long" can just
    not be squeezed into the 52-bit mantissa. On the other hand, 'float' would somehow
    fit, but because of the higher precision of the Number type, floating point computations
    would give different results in the converted code. So I also dropped support for this.
  
    In some cases a java library method that returns a 'long' is supported in a very specify way.
    To use this method, the java code needs to convert the result to a double or int explicitly.  
      
- Auto-boxing, Auto-unboxing not supported
    This feature would be a horror to get right in all conversion targets. Since its use
    is already quite disfavoured in the first place, the converter does not allow it at all.
      
- Method/constructor overloading may be less powerful
    Overloading is supported to some extent, but there are some restrictions.
    Specifically it is not possible to later add overloads to
    an already defined name in a child class.
      
- No hiding of fields and methods 
    No two instance fields in objects that are somehow inherited from each other can have the 
    same name - even if one or both are private. 
    Same holds for methods - but there the "name" is considered to be the 
    identifier in conjunction with the number-of-parameters.
    Static fields or methods do not have this restriction.
    Also local variables and parameters may shadow fields just as normally.

- Slightly different type inference algorithm
    Compared to the standard java compiler, there are some slight differences what kind of
    types the converter can actually infer for lambda expressions and for the "diamond" operator.
    Since type inference is undecidable in the general case, a best effort approach is done
    by the converter. This will not always succeed in the same set of cases as for the 
    standard java compiler. When this happens, the problem will become apparent at compile time.    
       
- Access to static members is not allowed by using an instance expression with side-effects
    It is legal in java to call a static method with something like: 
    exp.valueOf(4711)    // where exp evaluates to an object of type Integer 
    Since the expression will just be eliminated during conversion, it must not
    have any possible side effects.
	
- Covariant return types are not completely supported
    In the case that a class implements an interface method but with a return type
    that is a subtype of the one declard in the interface, then the 
    method call in C# may not be converted to using a proper down-cast. This
    then leads to a subsequent C# compiler error. For this specific case
    do a manual cast in the java code.
      
- Limited subset of java core classes
    The converter core itself provides a limited subset of the java core classes and
    also a limited number of methods in each. 
    Mainly the most crucial parts of java.lang and java.util are provided and a
    minimal version of java.io.PrintStream to make 'System.out' and 'System.err' available 
    for simple logging. 
    The java 8 Stream API is not provided, but similar functionality can be created
    using generics and lambda expressions. The Supplier, Function, Consumer, BiConsumer, 
    Predicate interfaces are provided to allow basic generic data transformation operations.
    See the document libraries.txt for a complete list.

- String.split() only accepts a simple search string
    Instead of supporting the whole regular expression framework for just this method, 
    the functionality is limited to have regular expressions that only match a single static
    string. To enforce this, the regex parameter must be a compile-time constant. 
      
- Arrays.sort() and List.sort() only work with a non-null Comparator. 
    To avoid implementing the whole concept of "natural ordering" and the
    Comparable interface, you must always provide an explicit Comparator.
    The java converter enforces this in a conservative way. If it can not detect
    the non-nullness of the parameter from the usage, you can make it obvious by
    calling an otherwise useless ".reversed().reversed()" on the comparator object.