VJET/VJETBootstraping

Overview

There are many cases where we need to enable extensions to Vjet. If we separate out what is possible based on the Eclipse Plugin Framework, we are generally talking about some sort of extensions to the code, libraries, runtime or type system. It is these areas that this document is about.

What is the overall concept?

We want to be able to locate some files (could be .js, .json, .txt or others) and have them meaningfully processed by the Vjet environment.

We have a few things to solve then: • Where do we look for these files (in some directory)? • Which files should we process? • How do we process each specific file?

What use cases do we need this capability?

Type Extensions (for typelibs like node.js for V8, Prototype, Scriptaculous) and Factory Function Resolvers (supporting functions like require(…) from CommonJS are two immediate cases that come to mind.

Isolate Bootstrap directory(s) and related code from /src

We don’t want to have bootstrap/extension directories/code being comingled with other source code. This is for many reasons: Separation of concerns Location flexibility Builder isolation What environment/code that needs to be available

Locating bootstrap directory

We can start with a directory called /vjetx. This directory will be part of the project structure. So, just like we have /src and /bin directories, we add /vjetx for Vjet type projects. This is a convention and easy to start with.

We could use property files or project configuration via properties, or manifest or such to define the location of the Vjet Extension directory (this is where we got the convention name vjetx).

For now we identify the extension directory in the .buildpath file:

<?xml version="1.0" encoding="UTF-8"?> <buildpath> <buildpathentry kind="bootstrap" path="vjetx"/> <buildpathentry kind="src" path="src"/> <buildpathentry kind="con" path="org.eclipse.dltk.launching.INTERPRETER_CONTAINER"/> <buildpathentry kind="con" path="com.ebay.tools.vjet2.core.SDK_CONTAINER/DEFUALT_SDK"/> </buildpath>

Bootstrap entry will be represented by BPE_BOOTSTRAP this will leave room for multiple bootstrap directories in future. GroupInfo is being extended to pass

GroupInfo.setBootstrapPath

GroupInfo.getBootstrapPath

This only supports one path.

What files will we process?

We want this mechanism to be flexible so what files to process are a question that should be answered per need. Currently we have: • Factory Function Resolver Registration • Type Extension Registration

To start with we can use a convention mapping. Later we should have pluggable mapping. The mapping is really something like MIME.

Our initial start with be to have a single file for both these cases. The hardwired file name will be bootstrap.js. Later we may have separate files and/or support more than 1 bootstrap*.js files.

Activity

We can define an activity as some bootstrap code, that when given the location of the bootstrap directory, is given a list of resources in that directory. The activity will select (filter patter) the resources (files) that meet its criteria. What the activity does with the matching resources is its own business?

Vjet will have some default activities; these were already mentioned (Factory Function Resolver Registration and Type Extension Registration). Later we will open up the mapping to other activities.

Factory Function Resolvers – .js files matching ffr*.js Type Extensions – .js files matching typeext*.js

For now we are combining these needs into a single file called bootstrap.js. It would look like:

var factoryFunctionMappings = { … }

var typeExtensions = { … }

The actual contents of each Object Literal, is described in the documents that talk about Factory Function Resolvers and Type Extensions. For now these will be the convention names used.

How are those files processed?

The two mentioned activities have separate documents on what they will do. The format for the factory function registration is regular JavaScript – basically an Object Literal. The format for the type extensions is also a simple Object Literal

However, there are some high-level capabilities they should perform. See the Bootstrap Lifecycle section.

Bootstrap Lifecycle

If we think of something like OSGI, then a bundle not only defines some code but also is subject to a basic lifecycle.

For our current needs the ability to complete some registration of resolvers or register some extension type information means these tasks have to happen before we start doing a type validation.

If we remove/close a project that has some extensions in it, we may need to do some unregistering of specific extensions.

From a high-level we basically have:

- Register/Initialize/Start - Stop/Un-initialize/De-register

It’s useful to note the usually your unwind process goes in the opposite order of the startup process.

We can see that if we registered some Type Extensions that when we removed them or deleted that project that those Type Extensions were removed.

What triggers the Bootstrap Lifecycle?

These are generally based on the Vjet tooling runtime itself and on stardard Eclipse Plugin processing/extensions.

Examples of such triggers:

Load/Unload a Project Open/Close a Project Adding/removing artifacts in a Project Changes to source in a Project Changes to a Projects dependencies etc…

The bootstrapping lifecycle must take project dependencies into account. If projA depends on B and B on C, then during bootstrap initialization we load C first, then B and finally projA. Usually for symmetry, we go in the opposite direction when unloading. We unload projA first, then B and finally C.

Dependent Projects

Bootstrap is first

We will process what is in the /vjetx directory before we do the normal Vjet source code. The activities in here will generally influence the processing of the normal source code in the /src directories and thus must be handled first.

Must work outside of Eclipse environment

We want to make sure this bootstrapping can work outside of the Visual Eclipse environment. This is so the headless build can work.

Vjojs Available or Not?

To start with we are not expecting the Vjo runtime to be available to the code in bootstrap.js. This just simplifies things.

Developers are writing simple JavaScript Object Literals – in our current cases no behavior, just data.

We pick OL’s for now over JSON just to simplify any dependencies on JSON itself.