index.html.haml

---
layout: base
---
.hero-unit{ :style=>"text-align: center"}
  %img.hidden-phone{ :src=>"images/mapstruct.png", :style=>"height: 120px"}
  %h1.h1-phone.visible-phone MapStruct
  %p Java bean mappings, the easy way!
  %p{ :style=>"padding-top: 15px;"}
    %a.btn.btn-large.btn-primary#btn-getting-started{ :href=>'#getting-started'} Get started &raquo;
    %a.btn.btn-large{ :href=>"#{site.base_url}/download" } Download &raquo;

    :javascript
      $('#btn-getting-started').bind('click', function(e) {
         e.preventDefault();
         var s = $(this.hash);
         $('html, body').animate({ scrollTop: $(this.hash).offset().top - 50 }, 300);

         // edit: Opera requires the "html" elm. animated
      });

.row
  .span4
    %h2 What is it?
    %p MapStruct is a code generator that greatly simplifies the implementation of mappings between Java bean types based on a convention over configuration approach.
    %p The generated mapping code uses plain method invocations and thus is fast, type-safe and easy to understand.

  .span4
    %h2 Why?
    %p Multi-layered applications often require to map between different object models (e.g. entities and DTOs). Writing such mapping code is a tedious and error-prone task. MapStruct aims at simplifying this work by automating it as much as possible.
    %p In contrast to other mapping frameworks MapStruct generates bean mappings at compile-time which ensures a high performance, allows for fast developer feedback and thorough error checking.

  .span4
    %h2 How?
    %p MapStruct is an annotation processor which is plugged into the Java compiler and can be used in command-line builds (Maven, Gradle etc.) as well as from within your preferred IDE.
    %p MapStruct uses sensible defaults but steps out of your way when it comes to configuring or implementing special behavior.

.row
  .span12
    %hr
    %h2 News
    - for post in site.posts[0, 3]
      .post
        %h3
          = post.title
        %h5
          = post.author + ", " + post.date.strftime( '%d %B %Y' )
        %p
          = summarize( html_to_text( post.content ), 30 )
        %p
          %a{ :href=>post.url} Read complete post &raquo;

    %p.links
      %a{ :href=>"#{site.base_url}/news" } More news &raquo;
      |
      %a{ :href=>"#{site.base_url}/news.atom" } News feed &raquo;

.row
  .span12
    %p &nbsp;
    %hr
    %a#getting-started{ :name=>'getting-started'}
    %h2 MapStruct in 2 minutes

.row
  .span4
    %p
      :markdown
        The following shows how map two objects using MapStruct.

        Let's assume we have a class representing cars (e.g. a JPA entity) and an accompanying data transfer object (DTO).

        Both types are rather similar, only the seat count attributes have different names and the type attribute is of a special enum type in the `Car` class but is a plain string in the DTO.

  .span8
    .tabbable
      %ul.nav.nav-tabs
        %li.active
          %a{ :href=>'#tab1', :'data-toggle'=>"tab"} Car.java
        %li
          %a{ :href=>'#tab2', :'data-toggle'=>"tab"} CarDto.java

      :javascript
        $('#tab1 a').click(function (e) {
          e.preventDefault();
          $(this).tab('show');
        });
        $('#tab2 a').click(function (e) {
          e.preventDefault();
          $(this).tab('show');
        });

      .tab-content
        .tab-pane.active#tab1
          %pre.prettyprint.linenums
            = preserve do
              :escaped
                public class Car {

                    private String make;
                    private int numberOfSeats;
                    private CarType type;

                    //constructor, getters, setters etc.
                }
        .tab-pane#tab2
          %pre.prettyprint.linenums
            = preserve do
              :escaped
                public class CarDto {

                    private String make;
                    private int seatCount;
                    private String type;

                    //constructor, getters, setters etc.
                }

.row
  .span12
    %hr
    %h3 The mapper interface
.row
  .span4
    :markdown
      To generate a mapper for creating a `CarDto` object out of a `Car` object, a mapper interface needs to be defined:

  .span8
    .tabbable
      %ul.nav.nav-tabs
        %li.active
          %a{ :href=>'#tab3', :'data-toggle'=>"tab"} CarMapper.java

      :javascript
        $('#tab3 a').click(function (e) {
          e.preventDefault();
          $(this).tab('show');
        });

      .tab-content
        .tab-pane.active#tab3
          -#
            %pre.prettyprint.linenums
              = preserve do
                :escaped
                  @Mapper (1)
                  public interface CarMapper {

                      CarMapper INSTANCE = Mappers.getMapper( CarMapper.class ); (3)

                      @Mapping(source = "numberOfSeats", target = "seatCount")
                      CarDto carToCarDto(Car car); (2)
                  }

          -# Adding the generated and prettified mark up from the listing above explicitely in order to insert badges

          <pre class="prettyprint linenums prettyprinted" style=""><ol class="linenums"><li class="L0"><span class="lit">@Mapper</span><span class="pln"> </span><span class="badge badge-info">1</span></li><li class="L1"><span class="kwd">public</span><span class="pln"> </span><span class="kwd">interface</span><span class="pln"> </span><span class="typ">CarMapper</span><span class="pln"> </span><span class="pun">{</span></li><li class="L2"><span class="pln">&nbsp;</span></li><li class="L3"><span class="pln">    </span><span class="typ">CarMapper</span><span class="pln"> INSTANCE </span><span class="pun">=</span><span class="pln"> </span><span class="typ">Mappers</span><span class="pun">.</span><span class="pln">getMapper</span><span class="pun">(</span><span class="pln"> </span><span class="typ">CarMapper</span><span class="pun">.</span><span class="kwd">class</span><span class="pln"> </span><span class="pun">);</span><span class="pln"> </span><span class="badge badge-info">3</span></li><li class="L4"><span class="pln">&nbsp;</span></li><li class="L5"><span class="pln">    </span><span class="lit">@Mapping</span><span class="pun">(</span><span class="pln">source </span><span class="pun">=</span><span class="pln"> </span><span class="str">"numberOfSeats"</span><span class="pun">,</span><span class="pln"> target </span><span class="pun">=</span><span class="pln"> </span><span class="str">"seatCount"</span><span class="pun">)</span></li><li class="L6"><span class="pln">    </span><span class="typ">CarDto</span><span class="pln"> carToCarDto</span><span class="pun">(</span><span class="typ">Car</span><span class="pln"> car</span><span class="pun">);</span><span class="pln"> </span><span class="badge badge-info">2</span></li><li class="L7"><span class="pun">}</span></li></ol></pre>

.row
  .span4
    :markdown
      The `@Mapper` annotation <span class="badge badge-info">1</span> marks the interface as mapping interface and lets the MapStruct processor kick in during compilation.

      The actual mapping method <span class="badge badge-info">2</span> expects the source object as parameter and returns the target object. Its name can be freely chosen.
  .span4
    :markdown
      For attributes with different names in source and target object, the `@Mapping` annotation can be used to configure the names.

      Where required and possible a type conversion will be executed for attributes with different types in source and target, e.g. the `type` attribute will be converted from the enumeration type into a string.

  .span4
    :markdown
       Of course there can be multiple mapping methods in one interface, for all of which an implementation will be generated by MapStruct.

      An instance of the interface implementation can be retrieved from the `Mappers` class. By convention, the interface declares a member `INSTANCE` <span class="badge badge-info">3</span>, providing clients access to the mapper implementation.

.row
  .span12
    %hr
    %h3 Using the mapper

.row
  .span4
    Based on the mapper interface, clients can perform object mappings in a very easy and type-safe manner:
  .span8
    .tabbable
      %ul.nav.nav-tabs
        %li.active
          %a{ :href=>'#tab4', :'data-toggle'=>"tab"} CarMapperTest.java

      :javascript
        $('#tab4 a').click(function (e) {
          e.preventDefault();
          $(this).tab('show');
        });

      .tab-content
        .tab-pane.active#tab4
          %pre.prettyprint.linenums
            = preserve do
              :escaped
                @Test
                public void shouldMapCarToDto() {
                    //given
                    Car car = new Car( "Morris", 5, CarType.SEDAN );

                    //when
                    CarDto carDto = CarMapper.INSTANCE.carToCarDto( car );

                    //then
                    assertThat( carDto ).isNotNull();
                    assertThat( carDto.getMake() ).isEqualTo( "Morris" );
                    assertThat( carDto.getSeatCount() ).isEqualTo( 5 );
                    assertThat( carDto.getType() ).isEqualTo( "SEDAN" );
                }

.row
  .span12
    %hr
    %h3 Tell me more!

.row
  .span12
    :markdown
      You like what you see? Then check out the [reference documentation](#{site.base_url}/documentation) to learn how to get started with MapStruct and which advanced features there are. In case you need help or want to propose a new feature just drop by on the [mapstruct-users](https://groups.google.com/forum/?fromgroups#!forum/mapstruct-users) group.

      You want to contribute to the development of MapStruct? That's great, [this page](#{site.base_url}/contributing) has all the information you need.