io.sphere.sdk.meta.ContributorDocumentation Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of sphere-jvm-sdk Show documentation
sphere-jvm-sdk
There is a newer version: 1.0.0-M26
package io.sphere.sdk.meta;

/**
 Developing the SDK


 
    please follow the Contribution Guidelines
    `sbt clean genDoc` creates Javadocs for all modules, it is available in target/javaunidoc/index.html
    opening the project with IntelliJ IDEA Ultimate might not work due to a bug, but using this solution works
 

 Construction
 
    
        A good class should have at least one explicit constructor.
    
    
        If multiple constructors are present, one constructor should have the role as primary constructor, so every other constructor has to directly or indirectly call the primary constructor.
    
    
        Prefer to create non-public constructors.
    
    
        The purpose of a constructor is to create a usable and consistent object, but not to fire actions. Prefer public static factory methods to constructors so that internals are hidden and to make it possible to turn the class into an interface later.
    
    
        Static factory methods should be named {@code of}, to be compliant to the Java 8 style, for instance {@link java.util.Optional#of(Object)}. It is okay to create additional aliases, like {@code empty()} for {@code of()}. Very specific factory methods can be named like this: {@code Xyz.ofSlug(final String slug)} or
        this: {@code Xyz.ofName(final String name)}. This naming convention makes clear what parameter type is required for the method compared to the more general method name like: {@code Xyz.of(final String guessWhat)}.
    
    
        If several constructors are present use the annotation {@link com.fasterxml.jackson.annotation.JsonCreator} to mark the right one for the JSON deserialization.
        
            
                If you don't do it you'll get an error message like
                {@code Caused by: com.fasterxml.jackson.databind.JsonMappingException: Conflicting property-based creators: already had [constructor for YOUR_CLASS, annotations: [null]], encountered [constructor for YOUR_CLASS, annotations: [null]]}
            
            
                Another reason for the previous error can be a static factory method which jackson tries to use for mapping by mistake, so you better annotate it with {@link com.fasterxml.jackson.annotation.JsonIgnore}.
            
            
                Also the error message {@code java.lang.RuntimeException: com.fasterxml.jackson.databind.JsonMappingException: Could not find creator property with name 'YOUR_PROPERTY_NAME' } indicates that you should annotate a factory method with {@link com.fasterxml.jackson.annotation.JsonIgnore}.
            
        
    
    
        In classic Jackson JSON projects you have to annotate the arguments for a constructor:
        @JsonCreator
public Xyz(@JsonProperty("id") String id)
 but with Java 8 it can be just  @JsonCreator
public Xyz(final String id)
    
 

 Classes
 
    Do not extend Object directly; if you can't find a base class simply use {@link io.sphere.sdk.models.Base} which implements equals, hashCode and toString with reflection.
 
 Polymorphism/Abstract Classes/Interfaces
 
 If you have to deserialize abstract classes or interfaces you need to specify the way how Jackson does the deserialization. Have a look into the source code of {@link io.sphere.sdk.productdiscounts.ProductDiscountValue} to find out how this can be done.
 If you use {@link com.fasterxml.jackson.annotation.JsonTypeInfo} with a property and you have already declared a property with the same name, it will may be written twice with different values, see also Stackoverflow.
 



 */
public final class ContributorDocumentation {
    private ContributorDocumentation() {
    }
}