• alapok
• ANC szabály
• DIC generátor
• DIC generátor XML
• dokumentumok
• getShell()
• paraméterezés
• ShellMap
• típus táblázatok

• A Shell adatbázis elérést biztosít Java programokból. JDBC-re épül, de annak használatát nagyban megkönnyíti.
• Képes java forráskódot generálni (DIC generátor) adatbázis tábla/view alapján, és ezekkel a java osztályokkal adatbázis műveletek végezhetők SQL-parancs kiadása nélkül:
• Alapfogalmak
  • Database Interface Class (DIC)
    Olyan osztály mely valamilyen adatbázis tábla/view strukturális megfelelője.
    Ezen osztály mezői szoros kapcsolatban vannak a tábla/view mezőkkel (megegyező név, leképezett adattípus).
    Shell esetén egy ilyen osztály @Table/@View annotációval van ellátva,
    és a táblával/view-val szoros kapcsolatban lévő mezői @Column annotációval ellátottak.
    
  • Database Interface Object (DIO)
    DIC példány.
  • Annotated Class (ANC)
    Olyan osztály mely legalább egy @Column annotációt tartalmaz.
  • Annotated Object (ANO)
    ANC példány.

• ANC szabály: Ha egy SQL-select egy ANC-be olvas be adatot, akkor a beolvasandó oszlopokat az ANC határozza meg !
  Így nem fordulhat elő hogy egy "SELECT * FROM ..." parancs működésképtelen legyen, mert a tábla/view új mezővel bővül. Tehát csak az ANC-ben lévő @Column oszlopokat kell beolvasni, azokat viszont minden körülmények között, még akkor is ha az SQL-select oszloplistájából hiányzik (ez viszont hibát okoz).
• Az ANC szabályból következik: ha egy táblából(view-ból) "SELECT * FROM ..." paranccsal olvasunk, és a tábla nagy mennyiségű adatot tartalmaz BLOB/CLOB mezőkben, de az ANC-ben ezek a BLOB/CLOB mezők nem szerepelnek, akkor a beolvasás gyors lesz, hiszen ezeket az oszlopokat nem olvassa ki a Shell a ResultSet-ből.

• Generátor indításakor a classpath-ban meg kell adni az adatbázis driver(ek) elérési útját is!
  A "java -jar" indítás nem működik, mert ilyenkor már nem állítható a classpath.
  
• Indításkor megadható program argumentumok:
  • xml.browse
    Default könyvtár az XML fájl választó ablakban. Nem kötelező.
  • xml.file
    Default XML fájlnév. Nem kötelező.
  • target.browse
    Default könyvtár a cél könyvtár választó ablakban. Nem kötelező.
  • target.dir
    Default cél könyvtár. Nem kötelező.
• Példa generátor indítására unix-on: Példa generátor indítására windows-on, ahol a parancsikonnak megfelelő indítási könyvtár van beállítva:
• Generátor működési szabályai:
  • Bármilyen könyvtár választható a generálás cél könyvtárának, de fájl sosem íródik felül.
  • A generált osztályok implementálják a java.io.Serializable interface-t.
  • A generált osztályok tagjai egy "SELECT * FROM TÁBLA(VIEW)NÉV WHERE 0 = 1" parancshoz tartozó ResultSetMetaData alapján kerül meghatározásra. A tábla/view oszlopnevek megegyeznek a java osztály tag neveivel, a típusok leképezései itt találhatók.
  • Előszőr az összes forráskód a memóriában jön létre, és ha ez sikeres, csak akkor kezdődnek el a fájl létrehozás műveletek.
  • Ha az 'XML fájl' mezője már tartalmaz egy fájlnevet melynek tartalma ezután módosul, akkor ezen a mezőn állva elég egy 'enter'-t nyomni az XML friss tartalmának beolvasásához.

• XML írja le a DIC generátornak hogy mit kell csinálnia: milyen adatbázishoz hogy kapcsolódjon, és mit generáljon.
• Használat:
  • Ha egy xml tag hiányzik, akkor a text-je null, tehát nincs adat megadva.
  • Ha egy xml tag létezik de nincs közé írva semmi, akkor a text-je üres string, tehát van adat megadva.
  • Az xml-ben nincs tárolva az adatbázis felhasználónévhez tartozó jelszó !
  • A kötelező gyökér elem: <generator>
• Adatbázis elérés tagok:
  • <database_driver>
    Adatbázis driver.
    Nem kötelező, mivel a JDBC4-ben már nem kell megadni. Ha meg van adva akkor egy Class.forName(...) hajtódik végre.
    Például: org.postgresql.Driver
  • <database_url>
    Adatbázis url.
    Kötelező.
    Például: jdbc:postgresql://localhost:5432/main
  • <database_user>
    Adatbázis felhasználónév, mellyel a generátor bejelentkezik az adatbázishoz.
    Kötelező.
  • <sql>
    SQL-parancs végrehajtása az adatbázishoz kapcsolódás után.
    Nem kötelező. Többször is előfordulhat.
    Például itt adhatjuk meg PostgreSQL esetén a 'search_path'-t.
• Generált fájlt jellemző tagok:
  • <encode>
    A generált fájl kódolása.
    Nem kötelező. Default érték: UTF-8
  • <line_separator>
    Sor elválasztó karakter(ek).
    Nem kötelező. A lehetséges két érték: 'UNIX' vagy 'DOS' kis- vagy nagybetűvel. Default érték: operációs rendszer sor elválasztó karakter(ek).
• Generált fájl tartalmát jellemző tagok
  • <indent>
    Generált forráskód bekezdés.
    Nem kötelező. Értéke 0..20 lehet. Default érték: 2
    Amikor a forráskódban egy szinttel beljebb vagyunk, ennyi space-szel kell betolni a sort.
  • <margin>
    Generált forráskód margó.
    Nem kötelező. Értéke 100..1000 lehet. Default érték: 150.
    Maximum ilyen oszlopszélességgel állítja elő a generátor a forráskódot.
    Csak a kód végére kerülő kommentben lévő SQL-parancsokra van hatással.
  • <package>
    Generált forráskód csomagnév (package név).
    Kötelező.
• Tábla és view adatokat jellemző tagok
  • <table>
    Adatbázis tábla befoglaló tag.
    Kötelező gyerekelemeket használni a tagon belül. A tag tetszőlegesen sokszor előfordulhat.
  • <view>
    Adatbázis nézet befoglaló tag.
    Kötelező gyerekelemeket használni a tagon belül. A tag tetszőlegesen sokszor előfordulhat.
  • <name>
    Adatbázis tábla/nézet neve. Ez a név fog szerepelni a @Table/@View annotáció paramétereként.
    Kötelező.
    A <table> vagy <view> gyerekeleme.
  • <access_name>
    Adatbázis tábla/nézet generátor által elérhető neve.
    Nem kötelező. Default érték: <name> tag értéke.
    A <table> vagy <view> gyerekeleme.
  • <class_name>
    Generált osztály neve (= fájlnév '.java' kiterjesztés nélkül)
    Nem kötelező. Default érték: <name> tag értékéből kiindulva '_' és '.' karaktereknél nagybetűre konvertálva.
    Például: <name>teszt_sema.teszt_table</name> esetén ha nincs megadva <class_name> akkor 'TesztSemaTesztTable' lesz az osztálynév.
    A <table> vagy <view> gyerekeleme.
  • <primary_key>
    Elsődleges kulcs oszlopok felsorolása.
    Nem kötelező, de ha nincs megadva több DIC-műveletet nem hajtható végre az osztályon:
    Shell.getObject(), Shell.updateObject(), Shell.deleteObject().
    Ha több kulcs van, akkor vesszővel kell őket elválasztani. Az itt felsorolt kulcsok lesznek @Id annotációval ellátva a generált forráskódban.
    A <table> vagy <view> gyerekeleme.
  • <skip>
    A generálásból elhagyandó oszlopnevek felsorolása.
    Nem kötelező. Olyan esetben érdemes használni amikor egy táblában/nézetben nagyméretű adat található egy (BLOB, CLOB, BYTEA típusú) oszlopban, és emiatt a táblából való lekérdezés túl időigényes lenne. A <skip> taggal ezek az oszlopok kihagyhatók a generált osztályból, így a lekérdezésben és egyéb műveletben sem vesznek részt.
    Ha több elhagyandó oszlop van, akkor vesszővel kell őket elválasztani. Nem sorolható fel olyan oszlop mely a <primary_key> tagnál szerepel.

• Mapping SQL and Java Types

• Egy javaslat a Shell példányt visszaadó metódusra, mely jndi-ből veszi fel az oracle adatbázis kapcsolatot:
• A getShell() hívása try-with-resources blokkban:

• Az SQL-parancsban egy paraméter ":" karakterrel kezdődik, mely után egy vagy több karakter következik a következő halmazból:
  • angol abc kisbetűi: a-z
  • angol abc nagybetűi: A-Z
  • aláhúzásjel: _
  • számjegyek: 0-9
  A paraméter vége egy olyan karakter mely nem eleme a halmaznak. Példák paraméterekre:
  
• Az SQL-parancsban a ":"-tal jelzett rész csak akkor számít paraméternek, ha előtte páros számú aposztróf van !
  
  Így tehát a következő SQL-parancsban csak a ":kod"-dal jelölt rész számít paraméternek:

• Numeric-cross-conversion(NCC):
  Ha adatbázisból ShellMap-be olvasunk be, akkor 3 különböző java osztályba kerülhetnek a numerikus adatok: Long, BigInteger, BigDecimal.
  Azonban a numerikus adat a ShellMap osztályból a getLong(), getBigInteger(), getBigDecimal() metódussal is beolvasható.
  Egyetlen megkötés hogy ez nem járhat adatvesztéssel (érték vagy tizedesjegyek elvesztése), különben ArithmeticException keletkezik.

• A shell az adatbázis oszlop típusokat DIC generáláskor, vagy ShellMap-be töltéskor, a következő java osztályoknak felelteti meg:

  Postgres adatbázis oszlop típus	Oracle adatbázis oszlop típus	Java SQL típus java.sql.Types	Java osztály megfeleltetés
  BIGINT INT8		Types.BIGINT (-5)	Long
  BYTEA		Types.BINARY (-2)	File
  BOOLEAN BOOL		Types.BIT (-7)	Boolean
  	BLOB	Types.BLOB (2004)	File
  		Types.BOOLEAN (16)	Boolean
  CHARACTER CHAR		Types.CHAR (1)	String
  	CLOB	Types.CLOB (2005)	String
  DATE		Types.DATE (91)	java.sql.Date
  		Types.DECIMAL (3)	ha (precision <= 0 vagy scale != 0) akkor BigDecimal különben:    ha (precision <= 18) akkor Long    különben BigInteger
  DOUBLE PRECISION FLOAT8		Types.DOUBLE (8)	BigDecimal
  		Types.FLOAT (6)	BigDecimal
  INTEGER INT INT4		Types.INTEGER (4)	Long
  NUMERIC DECIMAL	NUMBER	Types.NUMERIC (2)	ha (precision <= 0 vagy scale != 0) akkor BigDecimal különben:    ha (precision <= 18) akkor Long    különben BigInteger
  SMALLINT INT2		Types.SMALLINT (5)	Long
  TIME		Types.TIME (92)	java.sql.Time
  TIMESTAMP	DATE	Types.TIMESTAMP (93)	java.sql.Timestamp
  		Types.TINYINT (-6)	Long
  VARCHAR CHARACTER VARYING TEXT	VARCHAR2	Types.VARCHAR (12)	String
  		Types.ARRAY (2003) Types.DATALINK (70) Types.DISTINCT (2001) Types.JAVA_OBJECT (2000) Types.LONGNVARCHAR (-16) Types.LONGVARBINARY (-4) Types.LONGVARCHAR (-1) Types.NCHAR (-15) Types.NCLOB (2011) Types.NULL (0) Types.NVARCHAR (-9) Types.OTHER (1111) Types.REAL (7) Types.REF (2006) Types.ROWID (-8) Types.SQLXML (2009) Types.STRUCT (2002) Types.VARBINARY (-3)	Object

• Lehetséges java osztályok:

  Java osztály	SQL-parancs paraméter	ANC @Column	Generált DIC, ShellMap
  Short
  Integer
  Long
  Float
  Double
  BigInteger
  BigDecimal
  Time
  Timestamp
  java.sql.Date
  java.util.Date
  Boolean
  String
  Blob
  Clob
  Reader
  File
  Object
  	Lásd: SQL.setParameterInner2()	Lásd: Tool.resultSetToTargetObject()	Lásd: Tool.getColumnsFromMetaData()