io.odysz.semantic

Class DASemantics

java.lang.Object

io.odysz.semantic.DASemantics

Direct Known Subclasses:

DBSynmantics

public class DASemantics
extends Object

The default table semantics plugin used by semantic-DA.

The DASemantext use this to manage semantics configuration for resolving data semantics.

DASemantics is basically a semantics handler, DASemantics.SemanticHandler 's container, with subclass handlers handling different semantics (processing values).

What's DASemantics for?

Well, the word semantics is a computer science term. The author don't want to redefine this word, but here is some explanation what semantic-DA with semantic-transact is trying to support.

In a typical relational database based application, the main operation of data is CRUD. And the most often such data operation can be abstracted to some operation pattern, and they are always organized as a database transaction/batch operation described in SQL.

Take "book-author" relation for example, the author's ID is also the parent referenced by book's author FK. If trying to delete an author in DB, there are 2 typical policies can be applied by the application. The first is delete all books by the author accordingly; the second is warning and denying the operation if some books are referencing the author. Both of this must/can been organized into a transact/batch operation, with the second transact as check-then-delete.

In this case, you will find the FK relationship can be handled in a generalized operation, through parameterizing some variables like table name, child referencing column name and parent ID.

Take the DASemantics.smtype.parentChildrenOnDel for example, it's automatically support "deleting all children when deleting parent" semantics. What the user (application developer) need to do is configure a semantics item then delete the parent directly.

Now you (a developer) will definitely understand what's the "parentChildrenOnDel" for. Semantic-DA abstract and hide these patterns, wrapped them automatically into a transaction. That's what semantic- DA want to do.

How to Use

To use this function:

1. Configure the "semantics.xml". See example in test/resources/semantics.xml.
2. Set the configured semantics as context of Statement. See example in io.odysz.semantic.DASemantextTest. Then use Statement's subclass's commit() method to generate SQLs

Is this Enough?

The 9 or 10 types of semantics defined in DASemantics.smtype is enough for some enterprise projects. It depends on how abstract the semantics we want to support. But it seems enough for us, at least now.

Another consideration is that semantic-DA never take supporting all semantics logic as it's goal. It's only trying to release burden of daily repeated tasks. Fortunately, such tasks' logic is simple, and the burden is heavy. Let semantic-* handle these simple logic, that's semantic-* designed for. If the semantics is complex, use anything you are familiar with. But in this case semantic-* are still useful to do this tasks, if users are familiar with the lower level API.

Before doing that, check the semantics-cheapflow workflow engine first, which is based on semantics-*, and can handle typical - not very cheap if by our define - logics all necessary for enterprise applications. It's a good example illustrating that if the semantics is designed carefully, those semantics supported by this pattern is enough.

But it do needs the application developers follow some design conventions. If you need you own semantics implementation, implement the interface ISemantext, or simply initialize Transcxt with null semantics, which will disable semantic supporting. In that way, it's working as a structured sql composing API.

Author:

odys-z@github.com

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DASemantics.SemanticHandler
static class	DASemantics.ShExtFile Deprecated. replaced with ShExtFilev2 Save configured nv as file. args 0: uploads, 1: uri - uri field, 2: busiTbl - sub-folder, 3: busiId - not used, 4: client-name (optional) for saving readable file name Note For large file, use stream asynchronous mode, otherwise it's performance problem here. Whether uses or not a stream mode file up down loading is a business tier decision by semantic-jserv. See Anclient.jave/album test for example.
static class	DASemantics.ShExtFilev2 Save configured nv as file.
static class	DASemantics.smtype Semantics type supported by DASemantics.

Field Summary

Fields

Modifier and Type	Field and Description
protected io.odysz.transact.sql.Transcxt	basicTsx Static transact context for DB accessing without semantics support. Used to generate auto ID.
static String	ERR_CHK error code key word
protected ArrayList<DASemantics.SemanticHandler>	handlers
boolean	verbose

Constructor Summary

Constructors

Constructor and Description
DASemantics(io.odysz.transact.sql.Transcxt basicTx, String tabl, String recId, boolean... verbose) Note: basicTx is already created per the connection, i.

Method Summary

Modifier and Type	Method and Description
DASemantics	addHandler(DASemantics.SemanticHandler h)
void	addHandler(DASemantics.smtype semantic, String tabl, String recId, String[] args)
DATranscxt.SemanticsMap	createSMap(String conn)
DASemantics.SemanticHandler	handler(DASemantics.smtype sm)
boolean	has(DASemantics.smtype sm)
void	onDelete(io.odysz.semantics.ISemantext semantx, io.odysz.transact.sql.Statement<? extends io.odysz.transact.sql.Statement<?>> stmt, io.odysz.transact.sql.parts.condition.Condit whereCondt, io.odysz.semantics.IUser usr)
void	onInsert(io.odysz.semantics.ISemantext semantx, io.odysz.transact.sql.Insert statemt, ArrayList<Object[]> row, Map<String,Integer> cols, io.odysz.semantics.IUser usr)
void	onPost(io.odysz.semantics.ISemantext sx, io.odysz.transact.sql.Statement<? extends io.odysz.transact.sql.Statement<?>> stmt, ArrayList<Object[]> row, Map<String,Integer> cols, io.odysz.semantics.IUser usr, ArrayList<String> sqlBuf)
void	onUpdate(io.odysz.semantics.ISemantext semantx, io.odysz.transact.sql.Update satemt, ArrayList<Object[]> row, Map<String,Integer> cols, io.odysz.semantics.IUser usr)
DASemantics.SemanticHandler	parseHandler(io.odysz.transact.sql.Transcxt trb, String tabl, DASemantics.smtype semantic, String recId, String[] args)
static io.odysz.semantics.meta.TableMeta	replaceMeta(String tbl, io.odysz.semantics.meta.TableMeta m, String... connId) Use this to replace metas from DB for semantics extension.
static Object[]	requiredNv(String n, io.odysz.transact.sql.parts.AbsPart v, Map<String,Integer> cols, ArrayList<Object[]> row, String target, io.odysz.semantics.IUser usr) Force to set or extend a nv pair into row

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ERR_CHK

public static final String ERR_CHK

error code key word

See Also:

Constant Field Values

verbose

public boolean verbose

basicTsx

protected io.odysz.transact.sql.Transcxt basicTsx

Static transact context for DB accessing without semantics support.
Used to generate auto ID.

handlers

protected ArrayList<DASemantics.SemanticHandler> handlers

Constructor Detail

DASemantics

public DASemantics(io.odysz.transact.sql.Transcxt basicTx,
                   String tabl,
                   String recId,
                   boolean... verbose)

Note: basicTx is already created per the connection, i. e. connect id is known.

Parameters:

basicTx -

tabl -

recId -

verbose -

Method Detail

replaceMeta

public static io.odysz.semantics.meta.TableMeta replaceMeta(String tbl,
                                                            io.odysz.semantics.meta.TableMeta m,
                                                            String... connId)
                                                     throws io.odysz.transact.x.TransException

Use this to replace metas from DB for semantics extension.

Parameters:

tbl -

m -

connId -

Returns:

replaced meta

Throws:

io.odysz.transact.x.TransException

SQLException

Since:

1.4.25

addHandler

public DASemantics addHandler(DASemantics.SemanticHandler h)

addHandler

public void addHandler(DASemantics.smtype semantic,
                       String tabl,
                       String recId,
                       String[] args)
                throws SemanticException

Throws:

SemanticException

handler

public DASemantics.SemanticHandler handler(DASemantics.smtype sm)

createSMap

public DATranscxt.SemanticsMap createSMap(String conn)

parseHandler

public DASemantics.SemanticHandler parseHandler(io.odysz.transact.sql.Transcxt trb,
                                                String tabl,
                                                DASemantics.smtype semantic,
                                                String recId,
                                                String[] args)
                                         throws SemanticException

Throws:

SemanticException

has

public boolean has(DASemantics.smtype sm)

onInsert

public void onInsert(io.odysz.semantics.ISemantext semantx,
                     io.odysz.transact.sql.Insert statemt,
                     ArrayList<Object[]> row,
                     Map<String,Integer> cols,
                     io.odysz.semantics.IUser usr)
              throws SemanticException

Throws:

SemanticException

onUpdate

public void onUpdate(io.odysz.semantics.ISemantext semantx,
                     io.odysz.transact.sql.Update satemt,
                     ArrayList<Object[]> row,
                     Map<String,Integer> cols,
                     io.odysz.semantics.IUser usr)
              throws SemanticException

Throws:

SemanticException

onDelete

public void onDelete(io.odysz.semantics.ISemantext semantx,
                     io.odysz.transact.sql.Statement<? extends io.odysz.transact.sql.Statement<?>> stmt,
                     io.odysz.transact.sql.parts.condition.Condit whereCondt,
                     io.odysz.semantics.IUser usr)
              throws SemanticException

Throws:

SemanticException

onPost

public void onPost(io.odysz.semantics.ISemantext sx,
                   io.odysz.transact.sql.Statement<? extends io.odysz.transact.sql.Statement<?>> stmt,
                   ArrayList<Object[]> row,
                   Map<String,Integer> cols,
                   io.odysz.semantics.IUser usr,
                   ArrayList<String> sqlBuf)
            throws SemanticException

Throws:

SemanticException

requiredNv

public static Object[] requiredNv(String n,
                                  io.odysz.transact.sql.parts.AbsPart v,
                                  Map<String,Integer> cols,
                                  ArrayList<Object[]> row,
                                  String target,
                                  io.odysz.semantics.IUser usr)

Force to set or extend a nv pair into row

Parameters:

n - forced field

v - forced value

cols -

row - row to be expanded

target - for the table

usr - operator

Returns:

the extended or forced value's nv pair