"How to create TOS components" Tutorial : Part 2

Component Creation - Part 2

In this part of the tutorial we will illustrate the anatomy of a TOS java component.
We will not create a new component, not just yet, instead we will use an existing component to explore how Open Studio uses it, I promise things will make much more sens once you reach the end of this page.

You will need to have your Stuido open for this tutorial, as you will be asked to execute some simple exercises.

Anatomy of a Component  

Remember when in part 1 we explained that the jet template generates "java output code" snippets that are injected into the class that defines the job?
To be precise, for each component you normally have three templates (minimum one, maximum three) that will generate a java output code snipped each.
They correspond to the sections of the component

    A component can have three sections, called "begin","main" and "end"

The behavior of those sections depends on the component AND the way it is linked with other components in the job.
A little practice here will make things way more understandable and fun, so in your Studio, create an empty job that you will call "tutorial_1".

To experiment with components we are going to use a tJavaFlex, so search for it in the palette and drag it to the project, it should appear as tJavaFley_1, you should have something like this ->

Now inspect its parameters (just double click it).

You can see that it has three big text boxes called "start code", "main code" and "end code".
They are referring to the three sections we introduced before, because a tJavaFlex is a basic component whose templates (the begin,main and end templates) will just take whatever java code you write in them and will outoput it without alterations as "java output code".
This will allow us to perform some interesting experiments even before creating our first component.

You probably guessed that the start comes first, then the main and finally the end, let's just prove that.

In the start prameter, just write the following java code :

   System.out.println("I am the begin section");

In the main :

   System.out.println("I am the main section");

And in the end :

   System.out.println("I am the end section");

Now run the job and, no surprises there, you get in the console :

   I am the begin section
   I am the main section
   I am the end section

The result is quite obvious because the component is not linked to anything else, so the process is clear and simple.
Here you need to understand another basic concept :

    The java output code of a component is executed all together, it's sections begin, main and end become part of the same java class (the job).
Templates for the same sections are executed separately one from each other to generate the java output code.

To test the first part of the statement, we will define a variable in the begin section and get it's value from the main and the end one.

Add the following line at the end of your begin section :

   int myvar=1234;

And then some code to test it in the main and in the end, something like ::

   System.out.print("myvar is "+myvar); // in the main
   System.out.print("myvar is still "+myvar); // in the end

Ok, we got the basics I guess, now let's extend the exercise a bit.
Replace the myvar declaration in the begin section with

   System.out.println("I am the begin section");
   for (int myvar=0;myvar<10;myvar++)

Notice that we are opening a cycle and not closing it in the same section, instead we will close it in the end section :

   System.out.println("I am the end section");
   // here myvar is not defined, we are outside the for loop

Try to execute the job now, you will see that the main section is executed 10 times.

Still nothing special, right? So, let's see how the things can change when you have two components, connected together.
Make sure your code in the three sections of tJavaFlex_1 looks like this ->

Now copy and paste it (ctrl+C,ctrl+V), it will create another identical instance, with a different suffix number, does not need to be necessarily 2

Do not connect the two in any way, just execute the job.

What you should see in your console is that the two compoenents are executed one after each other, there is no way to tell which one goes first, but we don't care for now.

Now, get ready because things are about to get ugly, so, remember, we started from a condition where two instances of the same component were able to run in the same job with no issues.
Now connect them with a "row" connection, immediately you should notice that they become part of the same "box", this is not just a graphical thing, it's a key information.

    Components linked together with data or iteration connections are graphically represented in the same rectangular box, this means they are part of the same subjob.

Should we care? We should, hit F6 (run the job) if you don't believe me.
Guess what? Variable scope is the subjob, we have the same variable myvar in both instances, so we get a duplicate local variable error message.
This is the issue I anticipated in the part 1 of this tutorial.
I guess your java knowledge is enough to notice that the scope of the variable should be the cycle itself, so it should be safe to define them in two separate cycles, something like :

// first component instance
   System.out.println("I am the begin section");
   for (int myvar=0;myvar<10;myvar++)
   System.out.println("I am the main section and myvas is "+myvar);
   System.out.println("I am the end section");
// second component instance
   System.out.println("I am the begin section");
   for (int myvar=0;myvar<10;myvar++)
   System.out.println("I am the main section and myvas is "+myvar);
   System.out.println("I am the end section");

After all we saw before that this was actually the code being executed.
It was, but that was before we connected the two components.Once we created that row connection between them, everything changed.

Now the two compoenents are not executed anymore one after the other, instead their single sections of code are placed in a sequence, let's dicover how this sequence is defined.
To do that you need to modify the code in your second tJavaFlex to be similar to the following picture

Then execute the code, carefully read what is printed out in your console and start scratching your head.
There is a rule behind that, obviously :

    When multiple components in a subjob are linked with a chain of data connections, 1) The begin sections are executed first, starting from the last component in the chain, down to the first, then 2) the main sections are executed from the first compoenent in the chain up to the last.Finally 3) the end sections are executed in the same order as the main.

Confused? How's that possible? Good question, it's your homework to find it out!
How can you discover it? TOS generates java code to execute a job, and this code is there for you to analyse, so in the designer canvas, you have a little "code" tab, click that one and enjoy the beauty of the java code you just generated with a few clicks.
When the sections of your code get inserted into the job, some convenient commented lines are added, they can help you in locating the snippets, as an example, search for :
* [tJavaFlex_1 main ] stop


In the next part we will start coding our first component, make sure you understood everything up to here as it will be essential.
Hope you enjoyed this tutorial, if you have questions, ideas, complaints etc, you can contact us using the feedback module on this site.

Part 1  Part 3