What to know about Extensions?

Extensions making many useful extra features possible while working with Orcas, which is normally not possible at all.
Because of this it makes sense to get a quick impression of it before working with Orcas to figure out whether these extra features are useful in the own project or not. For example you could implement the convention that there has to be a PK at the first column by generating this PK. Extensions are always project specific.

Domain Extension

The domain-extension is a pre made extension, which can be used for 80% of all cases. It is always recommended to use this domain-extension and not to write his own if there is enough funtionality in the domain-extension because it only needs to be configured and can be used right after this.

How do extensions work?

An extension is an application component, which obtaines the whole data structure from all table scripts. E.g. this data structure contains all tables together with all columns, like defined in the scripts. An extension is able to change this data structure in every way. E.g.you can iterate across all tables from this data structure and add a new column called “ID” to every table. Extensions are also able to check, whether concrete conventions are fulfilled or not and to throw an exeption if necessary.

Extensions can also be used for many further mechanisms. E.g. a PL/SQL extension is able to replace the data structure with the current state of the database schema and to modify it quite easy (change tablespace, change varchar2 from byte to char…). A Java-extension would be able to read a UML-XML-file or JPA-annotated java classes and directly create tables from this. Notice: Because of technical reasons it is necessary to have at least eine table in the scripts. In case of doubt you have to implement a dummy table and delete it from the extension, is necessary.

Syntax-Extensions

It is also possible to extend the meta model of the data structure (e.g. extend type “Table” (Java-class or object-type) by a field. For this the Alias-Syntax-Extension (orcas_extensions/AliasSyntaxExtension.java) will often be used, which makes it possible to give an alias to a table very easy. In this case the alias is a a unique short form (3-4 letters).
Example: create table MYTABLE alis MYAL ( ...
This alias will now be used in the actual extensions e.g. generating names for constraints, sequences and/or columns. Syntax-extensions can only be implemented in Java.

How to create extensions?

Extensions are files, which will be droppped in the extention-folder (also look at: orcas_initialize). You’ll find some examples in the orcas_extensions folder. An example project, which uses extensions can be found right here: Extension-Demo:

  • Java Extension

    Extensions are Java-classes. These classes have to implement the interface (OrcasExtension). Typically extension-classes inherit from OrcasBaseExtensionWithParameter or TableVisitorExtension. The Java-classes have to be in the de.opitzconsulting.orcas.extensions package. The files have to be right there (without any sub directory).

  • Java Syntax-Extension

    Syntax-extentions are Java-classes. These one have to be derived from BaseSyntaxExtension. The Java-classes have to be in the de.opitzconsulting.orcas.syntax_extensions package. The files have to be right there (without any sub directory).

  • PL/SQL Extension

    Extensions in PL/SQL consist of a Package body. The script for this is stored as a .sql file in the extension directory. The specification for this will automatically be generated by Orcas. It contains only one function: “function run( p_input in ot_syex_model ) return of_syex_model;”, which needs to be implemented into the body.

  • PL/SQL Reverse-Extension

    Will be defined exactly like normal PL/SQL-extensions. They will not be executed at a normal run, but only at Reverse-Engineering. A PL/SQL Reverse-extension has to contain the keyword “reverse” in its name.

  • PL/SQL Helper-Package

    It is also possible to have your own package in the Orcas-schema. For this you only need to store the files (specification and body) in the extension-folder. These have to contain the keyword “helper” in its names.

Before writing your own extension, your should have a look at the example-extensions. For extensions with more complexity you should ask someone who is well informed before.

How do parameters work with extensions?

There is a possibility to parameterize extensions. It is also possible to transfer text variables to all extensions. For this the attribute extensionparameter will be used in the ant-Task todo: Link zu den ant-Tasksorcas_initialize. There is a special base class (OrcasBaseExtensionWithParameter) for parameterized extensions. This makes possible to use more than one parameter. For this you have to transfer the test variable into a map. You are now able to access a parameter by using the function getParameterAsMap. Example: To get the value “testtabs” from the parameter “tablespace”, your text variable could have the following value: “[xy:15,tablespace:testtabs]”.

Existing extensions

There are a few extensions, which can be use as copy template in your own project. Some extensions will be activated by specifying an alias, as long as they are integrated.

create table business_partners alias busi (...);

Alias to ID and PK

By specifying an alias a column <ALIAS>_ID (Number) and also a PK <ALIAS>_PK will be created automatically.

Alias to Sequence

By specifying an alias a sequence <TABLE_NAME>_SEQ for the table will be created automatically.

Alias to User-Stemp

This simplification can be activated, if the keyword “User-Stemp” will be added after the definition of the columns in a table script. As a result, four columns will be added.

  • <ALIAS>_INSERT_DATE
  • <ALIAS>_INSERT_USER
  • <ALIAS>_UPDATE_DATE
  • <ALIAS>_UPDATE_USER

Find Foreign Key

This extension makes possible to get the source- and target-columns of the constraint itself by specifying an alias. This extension only supports PKs with only one column.

constraint EXAMPLE_FK foreign key references TESTTABLE