1. Summary
  2. Files
  3. Support
  4. Report Spam
  5. Create account
  6. Log in

HowToUse

From j2cstranslator

Jump to: navigation, search

Contents

Usage

Command Line

That feature allow you to translate a series of eclipse projects from a given Workspace via an xml description file. The syntax of that xml file is :

 < translatorproject name="NameOfThatTranslatorProject"
                   outputdir="PathToBaseDirectoryForOutputSources">
   < project name="NameOfAnExistingProjectInTheGivenWorkspace"/>
   < project name="NameOfAnotherExistingProjectInTheGivenWorkspace"/>
 < /translatorproject>

Note that the value of "outputdir" attribute can be referenced in the translator.xml file of your eclipse project by using the ${ROOT} variable in the "output" and "testsOutputDir" attribute.
So to use it you need to go to your Eclipse directory :

Translate.bat -data PathToANExistingEclipseWorkspace /projectFile:projectFile.xml

where projecfFile.xml is an xml file that contains reference to existing eclipse project. You can find translate.bat here : http://j2cstranslator.svn.sourceforge.net/viewvc/j2cstranslator/trunk/CommandLine/

In Eclipse

From the export wizard, choose Other, then "ILOG Java to CSharp translator", then choose a project to translate and choose some options.
The translation will copy and rename your project (in order to keep original files unchanged), translate it and add some files in the original project (F5 to refresh the project):

  • src/main/translator
  • src/main/translator/translation.xml (describe the project to translate and set some options)
  • src/main/translator/configuration
  • src/main/translator/configuration/MyProject.mappingml (the mapping file, see below)

Warning:

  • The options you select in the configuration wizard are not yet saved in the translation.xml.
  • The UI not show all options (it's on my TODO list)


You also can use popup menus from :

  • Outline : Right Clic on a project, a package or a class, then "Convert this to c#"
  • Package Explorer : Right Clic, "Java2CSharp Translator" then "Translate"

How it works

Basically the translator will modify step by step your files. First it modify "normal" java files into something more simple (without nested, anonymous, ...) but still java compatible. Then we start replacing java construct by csharp construct. At any time the transformation remains in the java files. Last step is to rename the java file into .cs.

Process

  1. Read translator configuration files
  2. Read project dependence configuration files (dep1/.../translator/configuration/.mapping and dep1/.../translator/configuration/generated/*.mapping)
  3. Read project mapping files (currentProject/.../translator/configuration/*.mapping)
  4. Load the "transformers" (list of ASTVisitor classes) for the different passes (see below)
  5. Copy the project
  6. Apply that transformers on each compilation units (java buffer in modified)
  7. Generate a configuration file that contains all implicit modification done by the translator (in currentProject/.../translator/configuration/generated/)
  8. Save files (rename and copy java files)

Important files

  • translation.xml
  • mappings files

Translation file

That file is the most important one, it's use to set options (the output directory, ...) and change the way the translator acts.

< translation name="MyProject"
              sourcesOutputDir="${ROOT}/Generated/MyProject"
              testsOutputDir="${ROOT}/Tests/Generated/MyProject/"
              generateconffile="true"
              unitTestLibrary="testng"
              useGenerics="true">
 < depends project="otherEclipseProject"/>
< /translation>

The "translation.xml" file contains can contains the following options :

Mandatory

  • sourcesOutputDir = a directory : You can use Eclipse or Environement Variable with ${My_VAR} : indicate where to produce c# sources files

Optional

  • projectName = Name of the translator project
  • createTranslatorConfigurationFiles = indicate if the translator can automatically create the (default) needed files for translation
  • testsDestDir = a directory : You can use Eclipse or Environement Variable with ${My_VAR} : indicate where to produce c# test files
  • debug = true | false : Active debug mode
  • forceJUnitTest =
  • logFile = name and path of a log file (You can use Eclipse or Environement Variable with ${My_VAR})
  • refreshAndBuild = true | false : Auto refresh and force build before compile
  • generics = true | false : Indicate if the project use generics
  • Generation
    • flatPattern = a.package.name : In .Net it’s not mandatory to have the package name reflected on the file system (means that a class called com.ilog.MyClass does not need to be in a directory named com/ilog/MyClass.java). So with in that option you can specified a package name, for example “com.ilog”, and the translator just drop the creation of the directory hierarchy com/ilog. So you CSharp classes will be generated just under the generated directory your specified.
    • suffixForGenerated = a suffix : Automatically added the suffix (a string) to all generated sources files (not to class name only to filename)
    • exactDirectoryName = true | false : By default the generated directory name for the C# sources is the same as in Java (means for a package com.ilog, the created directory to put the csharp sources in will be com/ilog). Setting this option to true will generate the directory name that match exactly what you specified in the mapping file (if you choose to map com.ilog to Com.ILOG the created directory will be Com/ILOG/)
    • generateconffiles = true | false : used to generate a mapping file in multi-project environment. The generated file contains all implicit modifications performed by the translator (for example "move" member from interface to class). That file must not be modified, copied or moved, it's only for internal use.
    • sourceReplacementPolicy = DELETE | REPLACE | ONLY_ADD_NEW
  • Visual Studio Project generation
    • deprecated vsProject = true | false : generate a visual studio project file
    • vsProjectName = the name of the csproj to generate (You can use Eclipse or Environement Variable with ${My_VAR})
    • vsGenerationMode = merge | replace | generate
      • merge : add new files in the project
      • replace : replace all files by generated ones
      • generate : create a fresh csproj file
    • vsProjectEntrypoint = the fully qualified name of the entry point class
    • vsProjectType = CLASS_LIBRARY | CONSOLE_APPLICATION | WINDOWS_APPLICATION
    • vsVersion = VS2008 | VS2005
  • resources copy : Allow automatic copy of resources (non java file)
    • resourcesOutputDir : an existing directory to copy the resources in (You can use Eclipse or Environement Variable with ${My_VAR})
    • resourcesIncludePattern : a java-like regexpr
    • resourcesExcludePattern : a java-like regexpr
    • resourcesCopyPolicy : override | donotreplace
  • covariant = true | false : auto compute for return type covariance (time consuming)
  • autoProperties = true | false : auto compue properties (get/set couple)
  • createFiles = true | false : generate translator files (translation.xml and configuration/myproject.conf) needed for the first use.
  • unitTestLibrary = junit | junit4 | testng : indicate which unit test library is use
  • mappingAssemblyLocation = path to J2CsMapping assembly (You can use Eclipse or Environement Variable with ${My_VAR})
  • removeTempProject = true | false :
  • addNotBrowsableAttribute = true | false : automatically add attribute for all types and members
  • autoComputeDepends : true | false. Compute the list of dependences (Eclipse project) by using the eclipse classpath instead of having to write dependence in th "depends" section.
  • defaultPackageMappingBehavior : "capitalized" or "none" The default behavior for package mapping is to “capitalize” (Upper the first letter of each sub package). Setting this option to “none” will remains the package name unchanged. (not that the same option exist for method name but it’s still in beta).
  • defautIdentifierMappingBehavior : "capitalized" or "none" <BETA> The default behavior for package mapping is to “capitalize” (Upper the first letter of each sub package). Setting this option to “none” will remains the package name unchanged.
  • removeSerialVersionUIDFields : true | false : remove serialVersionUID fields during translation.
  • mavenStructure = true | false : If true the translator search for tests in src/test/java/.
  • tagToAddToComment = tagname to add on each comments
  • mapByteToSByte = true | false.
  • useAlias = true | false. Allow usage of alias in import clauses.
  • tabValue = a sequence of char that represent the value for a tab in generated file (default is "\t").
  • package_filter = a package name : filter for package
  • class_filter = a class name : filter for class
  • fillRawTypesUse = true | false : (experimental) Replace use of raw types with generics type
  • addPragmaForTest = a name. Add "#if NAME" .. #endid" at the begin/end of tests.
  • useOnlyXML = true | false.

Beta

  • useGlobal = true | false. Allow global:: directive in import clauses.
  • normalizeInterfaceName = true | false. Autoatically add "I" to the name of an interface.
  • profileForTranslation = to be documented
  • nullablePrimitiveTypes = true | false.
  • useIsolationForMapping = true | false.
  • sourceJDK = to be documented.
  • targetDotNetFramework = to be documented.


Experimental

  • nullableEnum = true | false.
  • simulation = true | false : (experimental)
  • proxyMode = true | false : (experimental) generate proxy (empty bodies)
  • collect public documented classes = to be documented


And a list of dependence (mostly eclipse project name) where the translator can find configuration files.

The differents passes

(from java2csharp.xml file)

  • Propagate data
  • Pre-Collect data
    • Search Enclosing access for inner class
    • Auto compute properties if needed
    • Autu compute covariance if needed (time consuming)
  • AST Refactoring : Eclipse like refactoring (time and resources consuming), can intoduce new class and be relaunch on them. Resulting project is fully java compatible.
    • Remove Extra Semicolon
    • "This" remover
    • Move class in method to inner
    • Fully Qualified Static Method Invocation
    • Move Anonymous In Constructor To Field
    • Replace Anonymous By Inner
    • Replace Interface Field Declaration
  • Collect data
  • AST Transformation : Perform change on class in order to be csharp friendly. Resulting project is fully java compatible.
    • Move Fields Initialization
    • Rename Field Declaration With Forbidden Name Class
    • Rename Type Variable
    • Move Interface Inner Or Nested Class To Top
    • Fix For Bug In Search Constructor
    • Abstract Class Explicit Implement Method From Interface
    • Adjust Qualifier for Moved Interface Field
    • Replace Array Variable Declaration
    • Add Break In Swich Case
    • Change Switch Char To Int
    • Change Equals Test For Boolean
    • Autoboxing Removal
    • Literals
    • Variable Visibility
    • Single Annotation
    • Collect public documented classes
    • Remove Private For Inner Members
    • Move Initializer To Constructor
    • Group Static Initializer
    • Foreach Checker
    • "This" cleaner
    • Fully-qualified enum invocation
    • Automatic infer generic argument
    • Fully generics
    • Check Defaut Return In generic Class
    • Qualified inner simple typeReference
    • Qualified Inner Type Reference
    • Fill Binding Tag
    • Prepare extension methods for Enum1
    • Prepare extension methods for Enum2
    • Move enum members
  • Collect and Format
    • Compute virtual override for methods
    • Store package name and imports
    • Rename class if needed
    • Applying covariance change
  • AST Replacement : Slightly modify the classes in order to be csharp like. Resulting project is no longer java compatible, but some parts of the AST remains "visitable".
    • Update Handler Tag
    • Compute Method Override
    • Change Interface Field Modifier
    • Rename fields with forbiddenName
    • Compute field access and method invocation
    • Rename field
    • Compute Type And Method Decl
    • Change Static Type Member Modifier
    • Covariance Changer
    • Change hierarchie
    • Remove Constructor Invocation
    • Remove Type Member
    • Enum
    • Annotations
    • Remove Annotations
    • Fill Dot Net Modifier
    • Properties
    • Imports Rewriter
    • Replace keyword in body
  • AST/Text Replacement : Perfoms modifications at type members level in degraded AST
    • Add constructor invocation
    • Add code to implementation
  • Text Replacement : Perfoms modifications at buffer level (text).
    • Replace Keyword
    • Fill Annotations
    • Remove Custom Comments
    • Insert Here Transformer
    • Keywords Transformer
    • Replacing class call transformer
    • Indent Transformer
    • Add pragma for test transformer
    • Extension methods
  • Save

mapping file

See Mappings

Limitations

  • Java generics must be full (that is, don't use RAW types instead of generics)
  • <?> as method return type or in type for local variable. Until now I didn't have any equivalent to that in .NET
  • Static inner class must not inherit from another class. The translator makes it became non static.
Personal tools