Skip to content

Commit

Permalink
Added demos, unified template args, fixed many bugs
Browse files Browse the repository at this point in the history
1. Added two demos that show a lot of server-side usage techniques.
2. Unified work with template arguments in server- and client-side
modes. It makes templates more portable.
3. Fixed a lot of typos in installers. Added uninstaller for the demo.
4. Update README
  • Loading branch information
Victor Osolovskiy committed Mar 2, 2015
1 parent 9c8210d commit 4598e25
Show file tree
Hide file tree
Showing 44 changed files with 1,889 additions and 223 deletions.
2 changes: 1 addition & 1 deletion .gitignore
Expand Up @@ -2,4 +2,4 @@
.idea
target
**/.svn
src/demo/**
src/demo/plsql/_temp/**
42 changes: 27 additions & 15 deletions README.md
Expand Up @@ -71,8 +71,8 @@ language called FTL.
> old [feature comparison](http://freemarker.org/fmVsVel.html) for more details.
FTLDB is an enhancement of FreeMarker for working with databases via JDBC. It
provides FTL methods for retrieving data from database queries and calls. It
also provides extra PL/SQL functionality for working in Oracle Database.
provides FTL methods for retrieving data from a database with queries and calls.
It also provides extra PL/SQL functionality for working in Oracle Database.

FTLDB may work either as a database application or as an external utility. We
call it *server-side* and *client-side* mode correspondingly.
Expand Down Expand Up @@ -111,10 +111,6 @@ editions except for XE).
The client-side mode suits for any versions of Oracle Database, as well as
PostgreSQL, MySQL, DB2 and other RDBMSs, which provide a JDBC driver.

The server-side support for PostgreSQL using
[PL/pgSQL](http://postgresql.org/docs/current/static/plpgsql.html) and
[PL/Java](http://github.com/tada/pljava) is in plans.


Usage comparison
----------------
Expand Down Expand Up @@ -183,14 +179,18 @@ begin

end gen_orders_plsql;

...

end generator;
/
```

The table creation PL/SQL script:
```sql
begin
generator.gen_orders_plsql();
end;
/
```

#### Server-side FTLDB
Expand All @@ -199,6 +199,8 @@ A fragment of the `generator` package:
```sql
create or replace package body generator as

...

function get_partitions return sys_refcursor
is
l_rc sys_refcursor;
Expand Down Expand Up @@ -247,13 +249,15 @@ begin
end gen_orders_ftldb;

end generator;
/
```

The table creation PL/SQL script:
```sql
begin
generator.gen_orders_ftldb().exec(true);
end;
/
```

#### Client-side FTLDB
Expand Down Expand Up @@ -299,9 +303,13 @@ comment on table orders is 'Orders partitioned by region.'
```

The table creation OS-shell script:
```
java -cp ../java/* ftldb.CommandLine orders.ftl 1> orders.sql
sqlplus scott/tiger@orcl @orders.sql
```

java -jar ftldb.jar orders.ftl >1 orders.sql
sqlplus scott/tiger@orcl @orders.sql
> **Notice**: Classpath may differ from the one specified above but must include
> `ftldb.jar`, `freemarker.jar` and the JDBC driver.
The result of all three executions is the `orders` table created and the
following script printed:
Expand Down Expand Up @@ -402,7 +410,7 @@ For example, on Windows you would run in the command line:

dba_install.bat orcl sys manager ftldb ftldb

On Linux (or another *NIX-like OS):
On Linux (or another *nix-like OS):

./dba_install.sh orcl sys manager ftldb ftldb

Expand Down Expand Up @@ -430,7 +438,7 @@ For example, on Windows you would run in the command line:

usr_install.bat orcl ftldb ftldb

On Linux (or another *NIX-like OS):
On Linux (or another *nix-like OS):

./usr_install.sh orcl ftldb ftldb

Expand All @@ -443,8 +451,8 @@ On Linux (or another *NIX-like OS):
You can change the default behavior and install FTLDB manually using scripts
from the `setup` directory.

In order to uninstall FTLDB run one of the `*uninstall` scripts corresponding to
your OS and installation type.
In order to uninstall FTLDB run one of the `*_uninstall.*` scripts corresponding
to your OS and installation type.


Security
Expand All @@ -470,11 +478,12 @@ Demo
The demo archive contains the installer of another standalone schema, which
demonstrates the work of FTLDB with unit tests and several manual scripts.

The installer is itself an example of client-side FTLDB usage (but it doesn't
access any database). Check the `*.ftl` files in the `setup` directory.
The installer is itself an example of client-side FTLDB usage (it doesn't access
any database but demonstrates several script composing techniques). Check the
`*.ftl` files in the `setup` directory.

The tests are used for the CI purposes and can be useful as a source of
server-side usage examples. Check the `ut_ftldb_api$process.prc` file, which is
server-side usage examples. Check the `ut_ftldb_api$process.pks` file, which is
probably the most interesting for you.

The demo scripts are not installed automatically. You should run them manually
Expand All @@ -494,6 +503,9 @@ installation script from the base directory with the following six parameters:
It creates the demo schema and runs the tests. After the installation has
finished you can connect to the demo schema and run the demos manually.

> **Notice**: Make sure that the target instance has the same TNS name on the
> server and the client. Otherwise some unit tests won't pass.

Building the project
--------------------
Expand Down
10 changes: 5 additions & 5 deletions pom.xml
Expand Up @@ -7,14 +7,14 @@

<groupId>ftldb</groupId>
<artifactId>ftldb</artifactId>
<version>1.0.0</version>
<version>1.1.0</version>

<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<name>FTLDB</name>
<description>FTLDB is an integration of FreeMarker Java template engine into Oracle Database.</description>
<description>FTLDB is an integration of the FreeMarker template engine into Oracle Database.</description>
<url>https://github.com/ftldb/ftldb</url>
<inceptionYear>2014</inceptionYear>

Expand All @@ -29,7 +29,7 @@
<scm>
<connection>scm:git:git://github.com/ftldb/ftldb.git</connection>
<url>https://github.com/ftldb/ftldb</url>
<tag>HEAD</tag>
<tag>master</tag>
</scm>

<dependencies>
Expand Down Expand Up @@ -123,15 +123,15 @@
<typ>DOUBLEDASHES_STYLE</typ>
<tps>DOUBLEDASHES_STYLE</tps>
<tpb>DOUBLEDASHES_STYLE</tpb>
<ftc>DOUBLEDASHES_STYLE</ftc>
</mapping>
<includes>
<include>src/**</include>
</includes>
<excludes>
<exclude>src/main/resources/**</exclude>
<exclude>**/*.policy</exclude>
<!-- TODO -->
<exclude>src/demo/**</exclude>
<exclude>src/demo/plsql/_temp/**</exclude>
</excludes>
</configuration>
<executions>
Expand Down
27 changes: 27 additions & 0 deletions src/demo/plsql/detection_of_changes/!install.sql
@@ -0,0 +1,27 @@
--
-- Copyright 2014-2015 Victor Osolovskiy, Sergey Navrotskiy
--
-- Licensed under the Apache License, Version 2.0 (the "License");
-- you may not use this file except in compliance with the License.
-- You may obtain a copy of the License at
--
-- http://www.apache.org/licenses/LICENSE-2.0
--
-- Unless required by applicable law or agreed to in writing, software
-- distributed under the License is distributed on an "AS IS" BASIS,
-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-- See the License for the specific language governing permissions and
-- limitations under the License.
--

@types.sql

@tabs.sql

@demo_whs_goods.sql

@demo_whs_goods_src.sql
@demo_other_sources.sql

@demo_dtoch_gen.pck

39 changes: 39 additions & 0 deletions src/demo/plsql/detection_of_changes/!readme.txt
@@ -0,0 +1,39 @@
====
Copyright 2014-2015 Victor Osolovskiy, Sergey Navrotskiy

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
====

Demonstration of solving a real applied problem: detection of changes in a
remote source.

1. On the demo schema run `!install.sql`. It will install the base objects,
which are needed to simulate a real system, and the generator package.

2. Explore the `demo_dtoch_gen` package.

3. Use `generate.sql` to generate utility objects for detection of changes in
three source tables.

4. Explore the result of generation and compare the new objects with their
templates.

5. Run `populate_data.sql` to fill two source tables with data.

6. Run the tests from `test_scr.sql` to see how the solution works.

7. Run `clean_result_of_generation.sql` to remove the generated objects and
return to point 2.

8. Run `!uninstall.sql` to remove all the directly installed objects (not
generated) of and return to point 1.
47 changes: 47 additions & 0 deletions src/demo/plsql/detection_of_changes/!uninstall.sql
@@ -0,0 +1,47 @@
--
-- Copyright 2014-2015 Victor Osolovskiy, Sergey Navrotskiy
--
-- Licensed under the Apache License, Version 2.0 (the "License");
-- you may not use this file except in compliance with the License.
-- You may obtain a copy of the License at
--
-- http://www.apache.org/licenses/LICENSE-2.0
--
-- Unless required by applicable law or agreed to in writing, software
-- distributed under the License is distributed on an "AS IS" BASIS,
-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-- See the License for the specific language governing permissions and
-- limitations under the License.
--

declare
l_scr ftldb_script_ot := ftldb_script_ot();
begin

for r in (
select 'drop ' || lower(lst.tp) || ' ' || lower(lst.nm) cmd
from user_objects o
join(
select 1 ord, 'PACKAGE' tp, 'DEMO_DTOCH_GEN' nm from dual union all
select 2 ord, 'VIEW' tp, 'DEMO_WHS_GOODS_SRC' nm from dual union all
select 3 ord, 'VIEW' tp, 'DEMO_OTHER1_SRC' nm from dual union all
select 4 ord, 'VIEW' tp, 'DEMO_OTHER2_SRC' nm from dual union all
select 5 ord, 'VIEW' tp, 'DEMO_WHS_GOODS' nm from dual union all
select 6 ord, 'TYPE' tp, 'DEMO_DTOCH_GEN_PR_NT' nm from dual union all
select 7 ord, 'TYPE' tp, 'DEMO_DTOCH_GEN_PR_OT' nm from dual union all
select 8 ord, 'TABLE' tp, 'DEMO_GOODS_IN_WHS' nm from dual union all
select 9 ord, 'TABLE' tp, 'DEMO_WAREHOUSES' nm from dual union all
select 10 ord, 'TABLE' tp, 'DEMO_GOODS' nm from dual union all
select 11 ord, 'SEQUENCE' tp, 'DEMO_CHANGE_SEQ' nm from dual union all
select 99 ord, '' tp, '' nm from dual where 1=2
) lst
on o.object_type = lst.tp and o.object_name = lst.nm
order by lst.ord
) loop
l_scr.append(r.cmd);
end loop;

l_scr.exec(true);

end;
/
38 changes: 38 additions & 0 deletions src/demo/plsql/detection_of_changes/clean_result_of_generation.sql
@@ -0,0 +1,38 @@
--
-- Copyright 2014-2015 Victor Osolovskiy, Sergey Navrotskiy
--
-- Licensed under the Apache License, Version 2.0 (the "License");
-- you may not use this file except in compliance with the License.
-- You may obtain a copy of the License at
--
-- http://www.apache.org/licenses/LICENSE-2.0
--
-- Unless required by applicable law or agreed to in writing, software
-- distributed under the License is distributed on an "AS IS" BASIS,
-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-- See the License for the specific language governing permissions and
-- limitations under the License.
--

declare
l_scr ftldb_script_ot := ftldb_script_ot();
begin

for r in (
select 'drop ' || lower(table_type) || ' ' || lower(table_name) cmd
from user_tab_comments tc
where tc.comments like '%@generated%'
union all
select 'drop package ' || lower(o.object_name) cmd
from user_objects o
where
o.object_name = 'DEMO_DTOCH' and
o.object_type = 'PACKAGE'
) loop
l_scr.append(r.cmd);
end loop;

l_scr.exec(true);

end;
/

0 comments on commit 4598e25

Please sign in to comment.