Module Developer's Tutorial
Target audience: jInfer module developers. Anyone who needs to extend jInfer capabilities by writing a new module.
This tutorial assumes that you are a seasoned Java developer. Having
experience with programming in some kind of framework (NetBeans Platform
above all) will help you a lot.
Make sure you have read the article on
architecture, data structures and inference process to understand what you
will be implementing. Having read the documentation for
remaining modules will help you too.
Also, before starting this tutorial, make sure you can
build jInfer from sources.
Overview
- Get NetBeans, jInfer sources, try a build.
- Decide on the type of module you want to create.
- Create new NetBeans module.
- Implement jInfer-specific interfaces.
- Implement your logic.
Building jInfer from sources
Refer to the official instructions.
What type of module?
First thing you need to realize is what kind of module you will be implementing. Is it going to be a part of the inference? If yes, what stage? Importing the initial grammar? Simplifying it? Exporting to resulting schema? If you are not sure what these terms mean, go read the articles on interence process again.
If your logic doesn't belong to the inference process, it might just extend one of the existing modules. Try looking for the code you would like to change.
New NetBeans module
This section assumes you have successfully imported jInfer in NetBeans.
- Expand the jInfer suite (brown puzzles icon).
- Right-click Modules, select Add New....
- On the first page, pick a name for your module. Click Next.
- On the second page, fill out the following:
-
Code base: this will be the package structure in which your code is placed.
If you want, follow our convention:
cz.cuni.mff.ksi.jinfer.yourmodule
. Otherwise choose something liketld.company.jinfer.yourmodule
. - Module display name: pretty obvious.
- Generate XML layer: you may want to check this option, but it doesn't really matter at this stage.
-
Code base: this will be the package structure in which your code is placed.
If you want, follow our convention:
- Click Finish.
Implement jInfer's specifics
This section will show how to deal with a new inference module - a simplifier
that does no actual simplification, just returns the grammar it got on input.
Your module will need a "main" class implementing the chosen inference
interface, annotated with a @ServiceProvider
annotation.
But first, we need to do some setup.
- Right-click the newly created module, select Properties.
- In Libraries > Module Dependencies, click Add Dependency....
- Filter for "base" and select Base as a dependency. Click OK.
-
Still in Properties, switch to Display category. Fill in:
- Display Name: Fill in a user-friendly name of your module.
- Display Category: type in jInfer.
- Short & Long Description: unleash your inner poet!
- Still in Properties, switch to API Versioning.
- Type
cz.cuni.mff.ksi.jinfer.base.interfaces.inference.Simplifier
in Provided Tokens. - Close Properties by clicking OK.
Now to the class itself.
- Add a new Java class: right click Source Packages in your new module, select New > Java Class....
- Fill in class name, for example MySimplifierImpl.
- Fill in package based on the Code base you selected while creating the module itself.
- Click Finish.
- In the heading line of the class, add
implements Simplifier
and fix the imports (you needSimplifier
from Base module). - Annotate this class with
@ServiceProvider(service = Simplifier.class)
. - NetBeans will complain about missing method implementations, add them.
-
Now fill in method bodies:
getName()
: return a string with module unix name, for example"mysimplifier"
.getDisplayName()
: return a user friendly module name, for example"My First Simplifier"
.getModuleDescription()
: return a short module description. You can also returngetDisplayName()
in this case.getCapabilities()
: for the moment, it is enough to returnCollections.emptyList()
.start()
: here is where your main logic belongs. In the case of a simplifier, you would do something with the rules and return a simplified grammar. For now, just docallback.finished(initialGrammar);
Run jInfer
At this moment, run the whole jInfer suite from the NetBeans you imported it into.
A new, child NetBeans should open with your module correctly installed. You can
now follow the User tutorial, just select your new
simplifier while creating a new jInfer project.
That's it! Start hacking you logic now!
Implement your logic
This is the part where you actually have to do some thinking :-) Implementing
an importer? Take that InputStream
and create some rules of it! Simplifier?
Take the rules you got and compact them somehow! Exporter? Take those rules and
write them out as a String
! It only depends on which module you are
in and algorithm you're implementing.
Dealing with jInfer and NetBeans Platform
You will soon get into situation where you need to interact either with jInfer or directly NetBeans. There is a tutorial for dealing with these cases.