What is java annotation? How it works?Let's make custom annotation.

In this article we are going to see Java Annotation in basic level, implementation and usages. This is very fundamental of Java . Almost all frameworks works based on this. Full AOP implemented using annotation.

So, What is annotation? 

By the name we can understand, it is like as tag , which used in books. Conceptually annotation works like tag for a specif code that we use. That means, it is data about data means meta data. In summary, when we need to apply meta data over our source then we use annotation. (again this is small use case , there are lot more and elaborate usages too)

Now, you can say, we can use annotation in other ways. Yes we do. Annotation can be used in different context and we can define context while doing this. Usually annotations can be scooped
1. Pre compilation / Source (it will process before compilation to give instruction to compiler)
2. Compile time or Deployment (it will process before deployment or during compilation , used for code generation, configuration (XML or etc files) changes)
3. Run time (it will process during run time, like changing behavior)

Run times are mostly used for dynamic behavior. Specially in AOP, when we define scopes it will change the app behavior. This is vastly used in spring.


How it works?
Annotation has 3 parts which work combined.

1. Declaration(where we declare annotation)
2. Using annotation (where we apply)
3. Processor (where we process data)

So, based on processor , annotation will perform its purpose. What ever we define in processor, it will be processed. (check detail in creating processor section)

Notes : 
-> Poplar frameworks like aspectj, spring actually inject code before after the code block (search for how spring works or "spring weaving" , you will get detail architecture).
-> via @Target , so, this processor will define its behavior on those purposes in scope ( we will see detail in below)

Let see more detail.

How to declare annotation?
Each annotation is a class file, so annotations are Type in java compiler.
So, if it is a public type, should be in separate java file.
The declaration keyword is @interface. In the example, I have used like this
public @interface Info {}
This is an annotation name Info, just simple.

Note :
1. Annotation can be public/intra package only (so no private/protected, Compiler Error)
2. As Annotation declared as @interface, it acts like interface, so no effect if you add abstract keyword before declaration.

So, AS we declared annotation, we need to define when it will be active. Java has helper annotation called @Retention which directs when it annotation will be invoked. There are three retention policy , CLASS, SOURCE, RUNTIME which defines the execution scope for annotation.
CLASS policy refers to annotation work in class files. That means code injection in byte code after compilation.
SOURCE policy annotation work on source code, before compilation. So, very good place if you are parsing source and applying additional code inside before compile.
RUNTIME simply works during run time at JVM. So, you can do all reflection based annotation using this policy(much easier to use)

I will use simply run time @Retention(RetentionPolicy.RUNTIME) , to have impact only on run time.

And, I will need to provide scope of annotation. Scope means, where it can be used in source code. Again, java compiler has @Target which defines this. It takes parameter ElementType(by enum) . I have used following like this.
@Target(value = { PACKAGE, TYPE, METHOD, FIELD, PARAMETER, LOCAL_VARIABLE, CONSTRUCTOR, ANNOTATION_TYPE })

Now, these are are pretty mandatory , you can use when you need. You need to know where you will let your coders to use your annotation and based on that you need to define the target area. The names are self explanatory. For example, if you want to limit your annotation to use for class fields only , choose only FIELD.

Note : Some predefined annotation ( @Deprecated , @Override, @SuppressWarnings, @SafeVarargs , @Documented, @Repeatable ) are also present in JDK, you can check their usages.

Now, Let come to Annotation Body. Annotation body act like as annotation parameter. That means, if your annotation has annotation body, when it is used in code, those values need to be inserted. That meas, we can enforce some data as input when some one use our annotation. I will use an enum Importancy defining priority and a string array as input. So, lets define that

public @interface Info {
    enum Importancy {HIGH,MEDIUM,LOW,CRITICAL}// enum declaration
    Importancy[] priority();//adding enum
    String[] values() ;//adding string array
}

Look at the declaration. Each member of Annotation declared like
Type parameterName();

And if you have default values, you can define

String[] values() default { "Default Value 1", "Default2" };

So, we know how to declare annotation , lets make Annotation processor.

How to make annotation processor? 

This part is kind of tricky. There are different ways to make the processor. When annotation came first, Java has build in annotation processor called APT(annotation process tool) . This APT tool was integrated form 1.6.
So, the best way to make an annotation processor to use this APT tool. This is basically a processor , following all standard processor rules. There is an abstract class for this "AbstractProcessor" , if you extend this, you need to apply processing , example
public class InfoAptProcessor extends AbstractProcessor{
    @Override
    public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment roundEnv) {
        //TODO -> Need to implement
        return false;
    }
}
There is very detail article in this link, where you can try to make @Factory annotation which will work as factory for object (factory design Patten)

Another useful way is, using reflection. Again, this is actually workable if retention policy is run time because reflection works in run time. If your annotation retention policy is source level, that means reflection cant find anything to work on.
That is why, frameworks , code injectors use APT tool which needs pre processing , need to be include in meta info to instruct compiler to run before compilation to work additional task.

In the below example, I made processing via reflection (so, run time as retention policy, try to change and see nothing in output)

Now, Let see, How to Use Annotation?
I first use annotation for unit testing with Junit & NUnit(for dotnet). Its very simple to use it

Syntax :
@AnnotationName :-> No parameter
@AnnotationName(Parameter1, Parameter2 ... ) ;-> One or more parameter
@AnnotationName(Parameter={array of values, typically enum or string}... ) -> with array inside one parameter.

Like as we use in Unit test :
@Test
public void testGetAllBugs() throws Exception{....}

Use in Spring Boot :(A Rest Controller, takes JSON format data )

@RestController//defining class as controller
public class BugWSController extends BaseController {
    @Autowired//dependency injection(IOC)
    private BugService bugService;

@RequestMapping(value = "/api/bugs/{id}", method = RequestMethod.GET, produces = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<Bug> getABug(@PathVariable("id") Long id) {
      ....
    }

Used in Spring Data :(a simple entity class representing a bug)

@Entity
public class Bug {
    @Id
    @GeneratedValue
    private Long id;
.....
....
}

Used for jcabi logging(Method level logging using AspectJ) :
@Loggable(Loggable.DEBUG)// will log automatically with code injection
    public static void show(){...}

Example(Create, Use Custom Annotation) : 

Problem : Let assume we need to get information from different part of source (test/code). Developers should be able to keep information from anywhere using annotation . So, we have to apply annotation @Info in every where (Class, method, constructor, field) in source code.
Typically we need to either print in string or store it some where for each usages. We will try to implement that via an annotation that can be used in our desired places and will show in command line about what info was inputted.

[I like this because , in Automation testing using selenium java , we can actually maintain logging of each tests/class/data for tests with our vastly writing lots of codes that makes test class more neat & clean]

So, Declaring an annotation 

import static java.lang.annotation.ElementType.*;
@Retention(RetentionPolicy.RUNTIME)
@Target(value = { PACKAGE, TYPE, METHOD, FIELD, PARAMETER, LOCAL_VARIABLE, CONSTRUCTOR, ANNOTATION_TYPE })
public @interface Info {
    enum Importancy {HIGH,MEDIUM,LOW,CRITICAL}
    Importancy[] priority();
    String[] values() default { "Default Value 1", "Default2" };//default values
}


Now we need a Processor :

Main duty :
1. See all classes in current package if it is using our annotation.
2. If using, find Class Information
3. Find constrictors of the class
4. Find fields of the class
5. Find Methods of the class

public class InfoProcessor {
public void processAnnotation() throws ClassNotFoundException, IOException {
        Class[] all = InfoProcessHelper.getAllClasses(this.getClass().getPackage().getName());
//Getting class
        for (Class aClass : all) {
            // System.out.println(aClass.getName());
            if (aClass.isAnnotationPresent(Info.class)) {
                Annotation annotation = aClass.getAnnotation(Info.class);
                Info info = (Info) annotation;
                System.out.println("This is a Class , Name ->" + aClass.getName());
                printAllInfo(info);
            }
// Getting Constructors
            int k = 0;
            for (Constructor constructor : aClass.getConstructors()) {
                if (constructor.isAnnotationPresent(Info.class)) {
                    Annotation constractorAnnotation = constructor.getDeclaredAnnotation(Info.class);
                    System.out.println("Constructor : " + k++ + ", Name ->" + constructor.getName());
                    printAllInfo((Info) constractorAnnotation);
                }
            }
// Getting fields
            int i = 0;
            for (Field f : aClass.getDeclaredFields()) {
                if (f.isAnnotationPresent(Info.class)) {
                    Annotation methodAnnotaitons = f.getAnnotation(Info.class);
                    System.out.println("Field : " + i++ + ", Name ->" + f.getName());
                    printAllInfo((Info) methodAnnotaitons);
                }
            }
// Getting methods
            int j = 0;
            for (Method aMethod : aClass.getDeclaredMethods()) {
                if (aMethod.isAnnotationPresent(Info.class)) {
                    Annotation methodAnnotaitons = aMethod.getAnnotation(Info.class);
                    System.out.println("Method : " + j++ + ", Name ->" + aMethod.getName());
                    printAllInfo((Info) methodAnnotaitons);
                }
            }
        }
    }

    private void printAllInfo(Info info) {
        for (Info.Importancy property : info.priority()) {
            System.out.println("Importancy:" + property.toString());
        }
        int i = 0;
        for (String aValue : info.values()) {
            System.out.println("Value:" + i++ + " : " + aValue);
        }
    }
}

To Help processor , I am using Helper to get all classes from current package :

public class InfoProcessHelper {
public static Class[] getAllClasses(String aPackageName) throws ClassNotFoundException, IOException {
        ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
        if (classLoader == null) {
            throw new ClassNotFoundException(aPackageName);
        }
        String path = aPackageName.replace('.', '/');
        Enumeration<URL> resources = classLoader.getResources(path);
        List<File> dirs = new ArrayList<File>();
        while (resources.hasMoreElements()) {
            URL resource = (URL) resources.nextElement();
            dirs.add(new File(resource.getFile()));
        }
        ArrayList<Class> classes = new ArrayList<Class>();
        for (File dir : dirs) {
            classes.addAll(findClasses(dir, aPackageName));
        }
        return classes.toArray(new Class[classes.size()]);
    }

    private static List<Class> findClasses(File dir, String packageName)
            throws NotDirectoryException, ClassNotFoundException {
        List<Class> classes = new ArrayList<Class>();
        if (!dir.exists()) {
            throw new NotDirectoryException("No directory in the path : " + dir);
        }
        File[] files = dir.listFiles();
        for (File aFile : files) {
            if (aFile.isDirectory()) {
                if (aFile.getName().contains(".")) {
                    classes.addAll(findClasses(aFile, packageName + "." + aFile.getName()));

                } else {
                    throw new NotDirectoryException("No directory in the path : " + aFile.getPath());
                }
            }
            if (aFile.getName().contains(".class")) {
                classes.add(Class.forName(packageName + '.' + aFile.getName().substring(0, aFile.getName().length() - 6)));
            }
        }
        return classes;
    }
}

[Note : if you need to know about Java reflection, you can check my old posts in this page on reflection ]

Now we need a simple class that uses our annotation :

@Info(priority = Info.Importancy.CRITICAL, values = {"this is Class", "Important class "} )
public class InfoUser {
    @Info(priority = Info.Importancy.LOW, values = {"this is Private field", "Field value "} )
    private String fname;
    @Info(priority = Info.Importancy.LOW, values = {"this is Private field", "Field value "} )
    private String lname;
  
    @Info(priority = Info.Importancy.CRITICAL, values = {"this is Default Constructor", "Method value "} )
    public InfoUser() {
    }

    @Info(priority = Info.Importancy.HIGH, values = {"this is parametrized Constructor", "Method value "} )
    public InfoUser(String fname, String lname) {
        super();
        this.fname = fname;
        this.lname = lname;
    }
    @Info(priority = Info.Importancy.MEDIUM, values = {"this is public method", "Method value "} )
    public String getFname() {
        return fname;
    }
    @Info(priority = Info.Importancy.HIGH, values = {"this is public method", "Method value "} )
    public void setFname(String fname) {
        this.fname = fname;
    }
    @Info(priority = Info.Importancy.MEDIUM, values = {"this is public method", "Method value "} )
    public String getLname() {
        return lname;
    }
    @Info(priority = Info.Importancy.HIGH, values = {"this is public method", "Method value "} )
    public void setLname(String lname) {
        this.lname = lname;
    }
    @Info(priority = Info.Importancy.CRITICAL, values = {"this is Very necesssary method", "Method value "} )
    public String getFullName() {
        return fname + " " + lname;
    }
}
This class extensively using our annotation in each step. And I am using dummy text just for quick code.

Now, the main thing, how to invoke this. In Junit(as junit run via reflection ) they use their own runner that runs all of this. As , we don't have runner, we need to call
new InfoProcessor().processAnnotation();

Any where from application.
I am using a main method in one of the class and running tha. 

public static void main(String... args) throws ClassNotFoundException, IOException {
        new InfoProcessor().processAnnotation();
}

So, we can see following in command line output.

Now, you might say, we cant call this from main. So how to do, I use (as best practice) a facade method containing all of my annotation processor executors and run at the end of my test execution , so that wither we get all info or log them. You can apply this way to log all of you test method, data etc.

Note : In Dot net , there is similar thing called attribute. Which is declared with [], works similar manner.


Please comment if you have a question

Thanks.. :) 

Measuring web page Performance(Navigation timing, User Experience)

In this article we are going to see how can we measure a webpage performance. As a part of SLA , when we need to measure performance for application , we need to know page performance. It will help to calculate Business SLA before finalizing project.
This is actually continuing post for measuring performance for Business/Application SLA for a page. You may visit my previous post for know more background. In here I will measure only timing.

Initial Background(Navigation Timing) :

First we need to know browser navigation timing. When a client( i.e browser) go to an URL , then there are certain request processing happens in background, like request goes to gateway,(local network) then go to DNS, then resolver, then resolve and goto to destination, each layer request and technological etc. I am avoiding detail as this post intend to know timing only. As this transformation is common for all web pages , w3c provide specification for each event. W3C also has specific definition & distribution for navigation timing. These are main resource & some publications.
Summary : Page navigation performance timing consist of following items
navigationStart , unloadEventStart , unloadEventEnd, redirectStart
redirectEnd, fetchStart, domainLookupStart, domainLookupEnd
connectStart , connectEnd , secureConnectionStart , requestStart
responseStart, responseEnd, domLoading, domInteractive, domContentLoadedEventStart
domContentLoadedEventEnd, domComplete, loadEventStart, loadEventEnd

And, each client (a browser) will get those via a common interface PerformanceTiming , which should be implemented by different browser to show those timing.

Most of modern browser implemented this. Here is the screen shot from IE11 & Chrome. (open browser tool and type window.performance in console, you can see following)

For detail understanding, you may visit google chrome developer's link . This is the gist.

For SLA, we may not need this broken time details, so we if we calculate Total primarily , it should be comprehensive. This detail info is helpful when we need to know breakdown analysis.

APDEX : There was a movement regarding Application Performance Index for applications among companies. This values refers to user satisfaction based on usages of the application. In short, Apdex refers to a value from 0-1 where higher value means full satisfaction. Simple formula
Apdext = (Satisfied Count + Tolerating Count / 2) / Total Samples

Example :  Let's assume collecting 10 samples from an application where SLA was 5s.
5 samples were below SLA(5s) , 3 samples are 5-8s, 2 samples are 8s+.
So, Apdex = (5+3/2)/10 = 0.65
Note : Apdex can also be measured page wise, transaction etc wise specifically .

More detail you can find
1. http://www.apdex.org/
2. https://en.wikipedia.org/wiki/Apdex


Now, let's see some method to measure these timing.

Measuring web page Performance(User Experience) in a browser :

Use Browser Tools :

All major browser has this, like chrome, IE11 or Firefox, if you press F12 or select developer tools you can see developers tool. In there, if you click network tab, you can easily see each request with time distribution.

Chrome :

IE :

Firefox : (browser tools + Firebug)

Use Browser Plugins/Addons : 

To make life easier , many developer community made browser plugins to get these timing easily. That means, beside browser tools, we can get those time using plugins or addons.

Performance Analyzer : Addon available for Firefox & Chrome, single click all summary with charts.

Detail report format is here : https://github.com/micmro/performance-bookmarklet
I prefer this due to summary view and very easy for QA, BA or any non technical personal to measure page timing very easily.

Some extra Chrome Addond does similar things :

1. Page performance :

2. Page Load Time :

3. Analyze Page Performance :

Gathering time by Running JS in Browser console:
We can run small javascript in browser console and get the navigation timing also(as I mention in basic part). From chrome/IE this is the command if you run
window.performance
You will be able to see full timing. (here is image from firefox)



Gathering time inside application by JS framework : It is very mature to have such capability of an web application to get timing inbuilt with application. There are lots of framework & libraries for that. One of them is Boomerang. It is simple a JS framework that you can use measure time. Again, like as other frameworks, it not only gives navigation timing, it can also give you detail of request processing timing which is very helpful to track down performance bottle knacks. 


Gathering timing with Jmeter-webdriver sampler : In Jmeter, we can drive selenium driven test to run browser and measure time. This way we can get time whenever we want , spatially useful when running any performance test in parallel. You can get full detail from this page ( section -> Client Side Performance Testing (Selenium/Firefox) ) of blog with multiple post on how to do that.

Gathering timing with a Proxy : We can also use local proxy to measure the timing when the app is running in a browser. My favorite is fiddler (for windows)

Fiddler : In fiddler , if we just add our necessary columns , we can monit or measure the timing. To do so,right click and click customize columns, and from collection select session timers, you will see full list of time collection from

I like the overall Elapsed time. If I select that and then we can see traffic captured with total timing (very good to measure time quickly without breakdown all complexity)




Gathering timing With Selenium functional tests :
1. Get Unit test time : As we see, selenium is driven by unit test runner, it is always easy to add timing flags in unit tests to get the timing. The following ways are useful.
Junit :

A. We can use manual timers , before test and after test to get the execution time. This consider as least useful as it takes lots of time to add code for each tests.

B. We can use timeout parameter inside each test (this timeout in MS)
@Test(timeout=100)

C. If you use Junit 4.12, then you can use stopwatch. Its simply done by making with @Rule. I am adding small experiential test class

public class TestForStopWatch {
     @Rule
     public Stopwatch stopwatch = new Stopwatch() {
         @Override
         protected void succeeded(long nanos, Description description) {
             print(description, "succeeded", nanos);
         }
         @Override
         protected void failed(long nanos, Throwable e, Description description) {
             print(description, "failed", nanos);
         }
         @Override
         protected void skipped(long nanos, AssumptionViolatedException e, Description description) {
             print(description, "skipped", nanos);
         }
         @Override
         protected void finished(long nanos, Description description) {
             print(description, "finished", nanos);
         }
     };
    @Test
    public void test() throws InterruptedException {
        long delta = 10;
        Thread.sleep(100L);
        assertEquals(100d, stopwatch.runtime(TimeUnit.MILLISECONDS), delta);
        Thread.sleep(900L);
        assertEquals(1000d, stopwatch.runtime(TimeUnit.MILLISECONDS), delta);
    }
     private static void print(Description description, String status, long nanos){
         System.out.println("Test -> "+     description.getMethodName()+" : Status "+ status+"Timeout : -> "+ TimeUnit.NANOSECONDS.toMicros(nanos));
     }
}

And in the output you can see test passed & printing in command line about tests.

From test(), you can see I wait 100ms, then compare stopwatch time (which prints) and assert the time . Doing the same thing again. Firs validation 100ms wait, and then 1000ms wait(100+900).

D. Junit Benchmark : This is small junit based benchmark library to run benchmark like full performance tests. Resource can be found here.
This also use @Rule. And this is very simple like as stopwatch implementation.
I am adding very small example.

public class JunitBenchmarkTests extends AbstractBenchmark{
    @After
    public void tearDown() throws Exception {
    }
    @Test
    public void test() throws InterruptedException {
        Thread.sleep(20);
    }   
    @BenchmarkOptions(benchmarkRounds=10,warmupRounds=1, concurrency=3 )
    @Test
    public void testWithBenchMark() throws InterruptedException {
        Thread.sleep(20);
    }
}

please see the command line information regarding performance test exertion 

From here, we can see, like as regular performance test, we can include thread number, iteration inside tests and measure timing. Very useful when you are testing API level test. (i will post detail separate blog)


2. Get Time by running JavaScript in Selenium : As we know, we can run JavaScript in selenium, so if we run navigation timing scripts in web driver, we can easily get the all type of timing. Here is one single helper class "NevigationTimeHelper" which takes a driver and get all timing.

public class NevigationTimeHelper {
    private WebDriver driver = null;
    Map<String, Object> timings = null;
    private final String JavaScriptForPerformance = "var performance = window.performance || window.webkitPerformance || window.mozPerformance || window.msPerformance || {};var timings = performance.timing || {};return timings;";
    public NevigationTimeHelper (WebDriver adriver){
        this.driver = adriver;
        getAllTiming();
    }
    private void getAllTiming(){
        JavascriptExecutor jsrunner = (JavascriptExecutor) driver;
        timings = (Map<String, Object>) jsrunner.executeScript(JavaScriptForPerformance);
    }
    private Long getAnTime(String name){        return (Long)timings.get((Object)name);     }
    public Long getnavigationStart(){        return getAnTime("navigationStart");    }
    public Long getunloadEventStart(){        return getAnTime("unloadEventStart");    }
    public Long getunloadEventEnd(){        return getAnTime("unloadEventEnd");    }
    public Long getredirectStart(){        return getAnTime("redirectStart");    }
    public Long getredirectEnd(){        return getAnTime("redirectEnd");    }
    public Long getfetchStart(){        return getAnTime("fetchStart");    }
    public Long getdomainLookupStart(){        return getAnTime("domainLookupStart");    }
    public Long getdomainLookupEnd(){        return getAnTime("domainLookupEnd");    }
    public Long getconnectStart(){        return getAnTime("connectStart");    }
    public Long getconnectEnd(){        return getAnTime("connectEnd");    }
    public Long getsecureConnectionStart(){        return getAnTime("secureConnectionStart");    }
    public Long getrequestStart(){        return getAnTime("requestStart");    }
    public Long getresponseStart(){        return getAnTime("responseStart");    }
    public Long getresponseEnd(){        return getAnTime("responseEnd");    }
    public Long getdomLoading(){        return getAnTime("domLoading");    }
    public Long getdomInteractive(){        return getAnTime("domInteractive");    }
    public Long getdomContentLoadedEventStart(){        return getAnTime("domContentLoadedEventStart");    }
    public Long getdomContentLoadedEventEnd(){        return getAnTime("domContentLoadedEventEnd");    }
    public Long getdomComplete(){        return getAnTime("domComplete");    }
    public Long getloadEventStart(){        return getAnTime("loadEventStart");    }
    public Long getloadEventEnd(){        return getAnTime("loadEventEnd");    }
}

Here we see, as window.performance gives a MAP type collection, so we have collect all measurement and parse/select as we need. So, I put each type in separate function name to keep things simple. 

[ I avoid other unit test platforms like Nunit , MS Unit, Xunit for dotnet to make things simple. Each unit test runner has its own implementation to measure time. ]

3. Browser MOB proxy with selenium :
If we have existing selenium script, we can use BrowserMOB proxy to measure time. This is very simply done by keeping webdriver running under proxy and we can get every performance measurement including in page JS execution time(if that is called by you selenium tests). Even you can store navigation timing detail as HAR(http archived file) to analysis further detail after tests. I will add separate posts on how to use browserMOB.

There are also APM tool vendors who provide these monitoring , to make things simple , I am avoiding those.

Please comment if you have any question

Thanks.. :)