001    /**
002     * Property of Hammurapi Group
003     */
004    package com.hammurapi.reasoning.spi;
005    
006    import java.lang.annotation.ElementType;
007    import java.lang.annotation.Retention;
008    import java.lang.annotation.RetentionPolicy;
009    import java.lang.annotation.Target;
010    
011    /**
012     * This annotation indicates that invocation of annotated method doesn't change
013     * observable (by rules) object model state. E.g. invocation of the method can 
014     * result in lazy loading of parts of the model, but this state change is not
015     * observable by model clients (i.e. rules).
016     *  
017     * This annotation is intended to be used in Java 5+ by rules pre-compilers. 
018     * Rules pre-compilers can perform execution optimizations such as 
019     * chaining of conditions on methods with this annotation.
020     * 
021     * For some cases, e.g. plain field getters, this annotation can be injected 
022     * into sources by automated code analysis tools. 
023     * 
024     * Optional <code>cost</code> attribute indicates relative cost of invocation of
025     * annotated method.
026     * @author Pavel
027     *
028     */
029    @Target(ElementType.METHOD)
030    @Retention(RetentionPolicy.SOURCE)
031    public @interface Const {
032            
033            /**
034             * Cost of method invocation. Rules pre-compilers can use this information
035             * to optimize sequence of operands in condition evaluation. E.g. if cost of 
036             * invocation Foo.getUnitPrice() is 5 and cost of Foo.getWeight() is 3 then 
037             * pre-compiler can optimize (foo.getUnitPrice()<20 && foo.getWeight()>50) to 
038             * (foo.getWeight()>50 && foo.getUnitPrice()<20) in order to invoke cheaper 
039             * method first and potentially avoid invocation of more expensive method.
040             * In this example difference in methods costs is small and distribution of 
041             * price and weight can cause this optimization result in more expensive 
042             * calculation in average, e.g. all instances are heavier than 50 and only 
043             * 5% are cheaper than 20.
044             * 
045             * Cost can be calculated by collecting performance data.  
046             * @return Invocation cost.
047             */
048            double cost() default 1.0;
049    }