Contributing to Hibernate using IntelliJ

Version 15

    Using IntelliJ with Hibernate sources

     

    Can’t code withoutThe best Java IDE

     

    Importing the project

    In general the IntelliJ support for importing Gradle projects should be the preferred means of importing the project.  Support for this feature is massively better in 14.1 then in previous versions.  In my experience IntelliJ 12.1 is the absolute bare minimum to have Gradle import working.  Each Hibernate project and its branches should identify any specific requirements for IntelliJ, JDK, etc.  Typically speaking, I find using Java 8 to run IntelliJ 14.1 the best experience.

     

    Note that automatic importing in IntelliJ IDEA 12 or 13 seems to be problematic on Mac OS X (mavericks). Here is a set of workarounds

    • edit /Applications/IntelliJ\ IDEA\ 13.app/Contents/Info.plist , look for JVMSession and change it to 1.7* ; this will make IntelliJ IDEA itself to run on JDK 7 - note that at the time of writing, it still did not solve the second gradle import problem and thus might be unnecessary
    • run ./gradlew idea from the command line and open the project in IntelliJ IDEA. Note that you will need to add the generated source folders (apt, antlr, ...). see the Annotation processor section for more info.

     

    Code style

    I found the code style not completely configurable for exactly how I personally like my formatting, but I have shared the code style I have configured in IntelliJ.  You can find our settings in this GitHub repository: hibernate/hibernate-ide-codestyles · GitHub.

    Here is an article on how to set it up in IntelliJ IDEA.

    The authoritative code style is defined by the CheckStyle checks file associated with the project; be sure to check against those prior to pushing.

     

    Debugging

    One important aspect to debugging through Hibernate sources is to make sure that the mere act of debugging does not forces proxies to initialize just so the debugger can "show" them.  In IntelliJ this is easily configured through what it calls "Data Type Renderers" and "Data Views".  Note that this information is relative to version 9.  To access this configuration, open your Settings (Ctrl+Alt+S) and under "IDE Settings" and locate "Debugger".  Expand "Debugger" and you will find both "Data Type Renderers" and "Data Views":

    1. "Data Views" is general configuration.  Here for sure you will want to disable the "Enable toString() object view".  In general, disable anything that would cause the debugger to force  initialization of the proxy.
    2. "Data Type Renderers".  We will need to define 2 specific type renderers:
        1. Entity Proxy renderer
          1. FQN : org.hibernate.proxy.HibernateProxy
          2. Rendering : use expression -> ((org.hibernate.proxy.HibernateProxy)this).getHibernateLazyInitializer().isUninitialized()  ? (  ((org.hibernate.proxy.HibernateProxy)this).getHibernateLazyInitializer().getEntityName()+"@"+System.identityHashCode(this)+"[proxy;id="+((org.hibernate.proxy.HibernateProxy)this).getHibernateLazyInitializer().getIdentifier()+"]"  ) : this.toString()
          3. Expanding : default; this will force the proxy to initialize (if not already) if the  user attempts to expand the node
        2. Collection Renderer
          1. FQN : org.hibernate.collection.AbstractPersistentCollection
          2. Rendering : use expression -> ((org.hibernate.collection.AbstractPersistentCollection)this).wasInitialized()  ? this.toString() : (  ((org.hibernate.collection.AbstractPersistentCollection  )this).getClass().getName()+"@"+ System.identityHashCode(this)+"  [uninitialized]" )
          3. Expanding : default; again, this will force the collection to initialize (if not already) if the  user attempts  to expand the node

       

      Source Header

      The best approach is to leverage the Copyright plugin (now a bundled plugin) to apply the license headers.  I set up all the types I deal with in the Copyright configuration (Settings > Copyright) for the template project and then select the specific one to use for each given project.  Anyway here is the standard license header template for Hibernate:

       

      /*
       * Hibernate, Relational Persistence for Idiomatic Java
       *
       * License: GNU Lesser General Public License (LGPL), version 2.1 or later.
       * See the lgpl.txt file in the root directory or <http://www.gnu.org/licenses/lgpl-2.1.html>.
       */
      
      
      

       

      Memory Tuning

      On my system personally I have had many issues with memory and GC when running IntelliJ.  I found these hints really helped in my situation:

      http://piotrga.wordpress.com/2007/06/26/intellij-ideaexevmoptions-revised-for-version-7-and-jdk-6/

       

      Annotation Processors

      It's currently recommended to explicitly disable the annotation processors in IntelliJ; from the project settings, "Java Compiler", make sure that

      • "-proc:none" is used as option to javac
      • raise the maximum heap size

      Then in the module settings:

      • for hibernate-core module add these source folders:

      target/generated-src/jaxb/main

      target/generated-src/logging/main

      target/generated-src/antlr/main

      • for hibernate-entitymanager, add:

      target/generated-src/jpamodelgen/test