([SORLWLQJ-DYD2EMHFWV

&RPSRQHQWV

86,1*25$&/(2%-(&76,164/-352*5$06
(NNHKDUG5RKZHGGHU2UDFOH&RUSRUDWLRQ

,1752'8&7,21
7KH2UDFOHLGDWDVHUYHUVXSSRUWVWKHGHILQLWLRQRIREMHFWW\SHVDQGWKHVWRUDJHRIREMHFWLQVWDQFHVLQWKHGDWDEDVH2EMHFWV
FDQEHPDQLSXODWHGXVLQJ-DYDSURJUDPPDWLFLQWHUIDFHVVXFKDV-'%&DQG64/-7KLVSDSHUH[DPLQHVDQGLOOXVWUDWHVREMHFW
PDQLSXODWLRQWKURXJKVWDWLF64/VWDWHPHQWVLQ64/-SURJUDPV:HGHVFULEHDJHQHUDOPHFKDQLVPZLWKZKLFKDQ\NLQGRI
64/GDWDPD\EHUHDGDQGZULWWHQE\-DYDLQIXOO\XVHUFXVWRPL]DEOHIDVKLRQ$VDQH[DPSOHZHVKRZKRZXVHUVFDQSURYLGH
WKHLURZQFXVWRPL]HGPDSSLQJIURP5$:FROXPQVLQ64/WRVHULDOL]HG-DYDREMHFWV7KHVDPHPHFKDQLVPLVWKHQHPSOR\HG
WRFUHDWHPDSSLQJVIURP64/REMHFWW\SHVWR-DYDFODVVHV:HVKRZKRZWKH-3XEOLVKHUWRROIRUPHUO\2EMHFW7\SH
7UDQVODWRUDVVLVWVLQWKHJHQHUDWLRQRIFXVWRPL]HG-DYDFODVVGHILQLWLRQVIRUWKHVHW\SHV6HYHUDOH[DPSOHVLOOXVWUDWHWKHVH
FRQFHSWVIURPWKHFUHDWLRQRIWKHREMHFWW\SHVLQWKHGDWDEDVHWRWKHH[DPLQDWLRQRIWKHJHQHUDWHG-DYDZUDSSHUVDQGWR
XVLQJWKHVHFODVVHVLQ64/-SURJUDPVIRUTXHU\LQJDQGXSGDWLQJREMHFWVLQWKHGDWDEDVH:HDOVRFRPSDUHWKH64/-DQG
-'%&DSSURDFKHV7KHXQGHUO\LQJUHSUHVHQWDWLRQRIREMHFWVLVVKDUHGEHWZHHQERWK$3,VZKLFKPDNHVDOO-DYDFODVV
GHFODUDWLRQVIRUREMHFWW\SHVIXOO\LQWHUFKDQJHDEOH2QWKHRWKHUKDQG64/-XVHUVEHQHILWIURPFRQFLVHFRGHREMHFWW\SHVGR
QRWQHHGDQ\VSHFLDOV\QWDFWLFWUHDWPHQWDVZHOODVIURPWUDQVODWHWLPHFKHFNLQJRI64/V\QWD[VHPDQWLFVDQGW\SH
FRPSDWLELOLW\
$IWHUJLYLQJDEULHILQWURGXFWLRQWR64/-ZHGLVFXVVLQVHFWLRQWKHEDVLFUHSUHVHQWDWLRQRI64/GDWD$JHQHUDO
FXVWRPL]DWLRQPHFKDQLVPIRUPDSSLQJ64/GDWDWR-DYDLVGHVFULEHGLQVHFWLRQDQGZHSURYLGHDQLQGHSWKH[DPSOH
PDSSLQJ5$:GDWDWR-DYDVHULDOL]DEOHREMHFWV,QVHFWLRQZHIRFXVRQWKHUHSUHVHQWDWLRQRI64/REMHFWW\SHV5()VDQG
FROOHFWLRQW\SHVLQ-DYD7KH-3XEOLVKHUWRROLVDOVRGLVFXVVHGDVZHOODVWKH-DYDFRGHJHQHUDWHGE\LW6HYHUDOH[DPSOHVVKRZ
64/FRGHIRUREMHFWFUHDWLRQDQGWKH64/-FRGHIRUFRUUHVSRQGLQJREMHFWPDQLSXODWLRQ7KHILQDOVHFWLRQFRQFOXGHVZLWKDQ
DVVHVVPHQWRIRXUDSSURDFKDQGDFRPSDULVRQEHWZHHQXVLQJWKH-'%&DQG64/-$3,VIRUH[SORLWLQJ64/REMHFWV
 64/-29(59,(:
7KLVVHFWLRQVXPPDUL]HVWKH64/-VWDQGDUGL]DWLRQHIIRUWDVZHOODVWKHEDVLFIHDWXUHVRIWKH64/-WUDQVODWRUSURJUDPVHHDOVR
>@:HH[DPLQHWKHEHQHILWVRIXVLQJ64/-DQGVXUYH\WKHEDVLFPHFKDQLVPWKDWSHUPLWVWKH64/-WUDQVODWRUWRVXSSRUW
2UDFOHVSHFLILFW\SHV
67$1'$5',=$7,21
64/-LVDVWDQGDUGL]DWLRQHIIRUWWKDWGHILQHVWKHLQWHURSHUDELOLW\EHWZHHQ-DYDDQG64/,WLVGULYHQE\VHYHUDOYHQGRUV
LQFOXGLQJ2UDFOH&RPSDT7DQGHP,%06\EDVH0LFURVRIW,QIRUPL[DQG6XQ0LFURV\VWHPV64/-3DUWVSHFLILHVWKH
HPEHGGLQJRIVWDWLF64/VWDWHPHQWVLQWKH-DYDODQJXDJHDQGKDVEHHQVXEPLWWHGWR$16,DVGUDIW;+:HUHIHUWR
WKLVGRFXPHQWZKHQZHWDONDERXWWKHVWDQGDUGIRU(PEHGGHG64/LQ-DYD
64/-75$16/$725
$UHIHUHQFHLPSOHPHQWDWLRQRIWKH64/-WUDQVODWRUZULWWHQLQSXUH-DYDKDVEHHQFUHDWHGE\2UDFOHDQGLWVSDUWQHUVDQGLV
SXEOLFO\DYDLODEOH7KHWUDQVODWRUFRQYHUWV64/-SURJUDPVZLWKHPEHGGHG64/VWDWHPHQWVLQWR-DYDSURJUDPVZLWKFDOOVWR
WKH64/-UXQWLPH7KLVLVVLPLODUWRWKH3UR &SUHFRPSLOHUWUDQVODWLQJ64/VWDWHPHQWVHPEHGGHGLQ&7KH64/-WUDQVODWRU
HPSOR\VDQRSHQDUFKLWHFWXUHSHUPLWWLQJLWWREHLQWHJUDWHGLQWRGLIIHUHQWGHYHORSPHQWHQYLURQPHQWVVXFKDVJUDSKLFDO,'(V
DVZHOODVWKH2UDFOHLVHUYHUVLGH-DYD90$GGLWLRQDOO\64/-FDQVXSSRUW64/FKHFNLQJDQG64/UXQWLPHFXVWRPL]DWLRQVIRU
DUELWUDU\GDWDEDVHVWKURXJK-DYDSOXJLQV
'HYHORSLQJDQ64/-DSSOLFDWLRQLVDVWUDLJKWIRUZDUGSURFHVVWKDWFRQVLVWVRIIRXUVWHSVDIWHUWKHFRGHLVZULWWHQ
 7UDQVODWLRQRI64/-VRXUFHILOHVZLWKWKH64/-WUDQVODWRU7KLVJHQHUDWHVQHZ-DYDVRXUFHILOHVZLWKFDOOVWRWKH64/-
UXQWLPHDVZHOODVDGGLWLRQDO64/-SURILOHILOHVFRQWDLQLQJDOOWKHLQIRUPDWLRQDERXWWKHVWDWLF64/VWDWHPHQWVWKDWZHUH
IRXQGLQWKH64/-VRXUFH
 &RPSLODWLRQRI-DYDVRXUFHVZLWKD-DYDFRPSLOHU
641
 ([SORLWLQJ-DYD2EMHFWV &RPSRQHQWV

 &XVWRPL]DWLRQRIWKHJHQHUDWHG64/SURILOHVIRULPSURYHGUXQWLPHSHUIRUPDQFHDQGYHQGRUVSHFLILFIHDWXUHV
 5XQQLQJWKHDSSOLFDWLRQXVLQJWKH64/-UXQWLPHOLEUDU\
8VXDOO\VWHSVWRDUHDXWRPDWLFDOO\SHUIRUPHGE\WKH64/-WUDQVODWRUE\WUDQVSDUHQWO\LQYRNLQJD-DYDFRPSLOHULQD
VXESURFHVV$WWUDQVODWLRQWLPHWKHVWDWLF64/VWDWHPHQWVLQWKHSURJUDPFDQEHFKHFNHGDJDLQVWDJLYHQGDWDEDVHVFKHPD
7KH64/-UXQWLPHFDQHLWKHUXVHDQDUELWUDU\-'%&GULYHURULWFDQEHLPSOHPHQWHGVHSDUDWHO\ZLWKRXWDQ\UHODWLRQVKLSWR
-'%&7KH2UDFOH64/-UXQWLPHXVHVWKH2UDFOH-'%&GULYHU

-DYD -DYD
64/-FRGH 64/- -DYD
VRXUFH FODVV &XVWRPL]H 5XQ
7UDQVODWLRQ &RPSLOHU
ILOH ILOH

2UDFOH 2UDFOH
)LJXUH64/-GHYHORSPHQWSURFHVV

$'9$17$*(62)64/-
$VVXPH\RXZDQWHGWRFUHDWH-DYDDSSOLFDWLRQVWKDWUHTXLUHGDWDEDVHDFFHVV6KRXOG\RXFRQVLGHU64/-UDWKHUWKDQWKH-'%&
$3,IRUGDWDEDVHFRQQHFWLYLW\"7KHIROORZLQJDUHEHQHILWVSURYLGHGE\64/-
 DPXFKPRUHFRQFLVHV\QWD[IRUGDWDEDVHDFFHVV
 VWURQJW\SLQJHJRITXHULHVWKURXJKLWHUDWRUW\SHVDQGRIFRQQHFWLRQVWKURXJKFRQQHFWLRQFRQWH[WW\SHV
 FKHFNLQJRIV\QWD[DQGVHPDQWLFVRIDOO64/VWDWHPHQWV
 IXOOELQDU\SRUWDELOLW\RI64/-SURJUDPVWKURXJKPXOWLYHQGRU$16,VWDQGDUGL]DWLRQLQFOXGLQJWKH64/-UXQWLPH
DGGLWLRQDOXQLIRUPLW\LVSURYLGHGWKURXJKWKHWUDQVODWRUUHIHUHQFHLPSOHPHQWDWLRQ
 SOXJLQDUFKLWHFWXUHIDFLOLWDWHVWRROVXSSRUWIRU64/-)RUH[DPSOHERWK2UDFOH-'HYHORSHUDQGWKH2UDFOHL-DYD90
LQWHJUDWHWKH64/-WUDQVODWRU
 FXVWRPL]DWLRQRIWKHUXQWLPHSURILOHZKLFKGHVFULEHVWKHVWDWLF64/VWDWHPHQWVHQFRPSDVVHV
• SHUIRUPDQFHHQKDQFHPHQWVHJWKURXJKFDFKLQJRUSUHFRPSLODWLRQ
• DGGHGIXQFWLRQDOLW\VXFKDVWKHVXSSRUWRIYHQGRUVSHFLILFW\SHV
• PLJUDWLRQVXSSRUWDQG
• GHEXJJLQJRUORJJLQJIXQFWLRQV
 PXOWLYHQGRUVWDQGDUGIRUHPEHGGHGVWDWLF64/LQ-DYD
(YHQIRUDSSOLFDWLRQVWKDWFRQWDLQVRPHG\QDPLF64/PL[HGLQZLWKVWDWLF64/VWDWHPHQWVXVLQJ64/-PD\EHDGYDQWDJHRXV
VLQFHLWLVSRVVLEOHWRPL[DQGPDWFK64/-DQG-'%&LQWKHVDPHDSSOLFDWLRQ6SHFLILFDOO\FRQQHFWLRQVDVZHOODVUHVXOWVHWV
FDQEHVKDUHGEHWZHHQERWK$3,V64/-DQG-'%&FRQVWLWXWHFRPSOHPHQWDU\WHFKQRORJLHVDQGVWUHQJWKV:KLOH64/-SURYLGHV
PRUHFRQFLVHV\QWD[IRUVWDWLF64/LWUHOLHVRQWKHHVWDEOLVKHG-'%&LQWHUIDFHIRUHPEHGGLQJG\QDPLF64/LQ-DYD
,WVKRXOGDOVREHQRWHGWKDWWKH64/-UXQWLPHLVLPPHGLDWHO\DYDLODEOHRQWRSRIDQ\-'%&GULYHU7KLVPHDQVWKDW64/-
DSSOLFDWLRQVFDQEHGHSOR\HGZKHUHYHU-'%&LVGHSOR\HGVXFKDVRQDWKLQFOLHQWDIDWFOLHQWRULQWKHVHUYHU
64/-6833257)2525$&/(7<3(6
64/-FDQVXSSRUW2UDFOHW\SHVWKURXJKDQ2UDFOHVSHFLILFFXVWRPL]DWLRQRIWKH64/-UXQWLPHSURILOH7KLVFXVWRPL]DWLRQ
ZLOOEHDXWRPDWLFDOO\SHUIRUPHGZKHQ\RXXVHWKH64/-WUDQVODWRUWKDWLVSURYLGHGZLWKWKH2UDFOHLGDWDEDVH,QWKLVSURFHVV
UXQWLPHFDOOVWRVWDQGDUG-'%&HQWU\SRLQWVVXFKDVgetObject()DQGsetObject()DUHUHSODFHGZLWKFDOOVWR2UDFOH·V
-'%&$3,
641
 ([SORLWLQJ-DYD2EMHFWV &RPSRQHQWV

:HGRH[SHFWWKH64/-VSHFLILFDWLRQWRHYROYHLQWKHIXWXUHWRHQFRPSDVVVWUXFWXUHG64/W\SHVVXFKDVWKRVHWKDWZHUH
LQWURGXFHGLQ-'%&DQGDUHVXSSRUWHGSUHOLPLQDULO\LQWKH2UDFOHL-'%&GULYHUV&XUUHQWO\VXSSRUWIRU2EMHFW7\SHV
FDQRQO\EHSURYLGHGDVDYHQGRUVSHFLILFH[WHQVLRQ
7KH2EMHFW7\SHVXSSRUWWKDWLVRXWOLQHGKHUHLVEDVHGRQWKHHIILFLHQWGLUHFWUHSUHVHQWDWLRQRIWKH64/GDWD7KHQH[W
VHFWLRQSURYLGHVDGHVFULSWLRQRIWKLVUHSUHVHQWDWLRQ
64/'$7$7<3(6$1'-$9$2%-(&76
2UDFOH·V-'%&GULYHU>@LQWURGXFHVDQHZSDFNDJHoracle.sqlWKDWFRQWDLQV-DYDFODVVHVFRUUHVSRQGLQJWRDOOH[LVWLQJ
64/W\SHV,QDGGLWLRQWRSURYLGLQJHIILFLHQWORZOHYHOUHSUHVHQWDWLRQDQGPDQLSXODWLRQRI64/GDWDDOORIWKHVHW\SHVDOVR
SHUPLWIXOOFXVWRPL]DWLRQIRUXVHUSURYLGHG-DYDFODVVHV7KLVFXVWRPL]DWLRQPHFKDQLVPLVGHVFULEHGLQVHFWLRQDQGLWDOVR
IRUPVWKHEDVLVIRUUHDGLQJDQGZULWLQJ64/2EMHFW7\SHVDVLQVWDQFHVRI-DYDFODVVHV
64/7<3(6$1'25$&/(64/&/$66(6
7KHWDEOHEHORZRXWOLQHVWKHFRUUHVSRQGHQFHEHWZHHQ64/W\SHVDQGoracle.sqlFODVVHV$OO-DYDUHSUHVHQWDWLRQVRI64/
GDWDLQWKHVHFRQGFROXPQVXEFODVVWKH-DYDW\SHoracle.sql.Datum $OORIWKHVHFODVVHVDOVRKROGDELQDU\UHSUHVHQWDWLRQ
RIWKH64/GDWDLQWKHIRUPRIDbyteDUUD\,WLVUHWXUQHGE\WKHgetBytes()PHWKRG
64/7\SH -DYDUHSUHVHQWDWLRQ -'%&7\SHFRGH $VVRFLDWHGZLWK64/7\SH1DPH
$OO1XPHULF7\SHV oracle.sql.NUMBER OracleTypes.NUMBER QR
CHAR, VARCHAR, oracle.sql.CHAR OracleTypes.CHAR QR
VARCHAR2
DATE oracle.sql.DATE OracleTypes.DATE QR
RAW oracle.sql.RAW OracleTypes.RAW QR
ROWID oracle.sql.ROWID OracleTypes.ROWID QR
CLOB oracle.sql.CLOB OracleTypes.CLOB QR
BLOB oracle.sql.BLOB OracleTypes.BLOB QR
BFILE oracle.sql.BFILE OracleTypes.BFILE QR
2EMHFW7\SH oracle.sql.STRUCT OracleTypes.STRUCT \HV
REF7\SH oracle.sql.REF OracleTypes.REF UHIHUHQFHVDQ2EMHFW7\SH
9DUUD\RU1HVWHG7DEOH oracle.sql.ARRAY OracleTypes.ARRAY \HV
7DEOH5HSUHVHQWDWLRQRI64/'DWDLQ-DYD

7KH&/2%%/2%DQG%),/(FODVVHVHQFDSVXODWHORFDWRUW\SHVDQGSURYLGHDVWUHDP$3,IRUDFFHVVLQJDQGPDQLSXODWLQJ
WKHDFWXDOGDWD7KH6758&7$55$<DQG5()FODVVHVFRUUHVSRQGWRQDPHGW\SHVYDUUD\VQHVWHGWDEOHVRUUHIHUHQFHVWR
QDPHGW\SHVUHVSHFWLYHO\ZHZLOOH[SODLQWKHVH64/W\SHVIXUWKHULQVHFWLRQ7KHFODVVHV180%(5&+$5'$7(
5$:DQG52:,'SURYLGHVHYHUDOFRQYHUVLRQVIURPWKH64/GDWDWRQDWLYH-DYDW\SHV
7KH2UDFOH-'%&GULYHUSURYLGHVDGGLWLRQDOPHWKRGVVXFKDVgetNUMBER()DQGsetNUMBER()HWFIRUUHDGLQJDQG
ZULWLQJWKHVHoracle.sqlW\SHVRQ2UDFOHUHVXOWVHWVDQGVWDWHPHQWV
64/-6833257)2525$&/(64/&/$66(6
64/-DOVRVXSSRUWVDOORIWKHW\SHVLQoracle.sqlGLUHFWO\8VHUVPD\GHFODUHKRVWYDULDEOHVRIWKHVHW\SHVDQGXVHWKHPWR
PDWHULDOL]HUHVXOWVHWFROXPQVWRSDVVYDOXHVLQ'0/VWDWHPHQWVRULQVWRUHGIXQFWLRQVSURFHGXUHVDQG3/64/EORFNV

OracleSQLJ currently does not support the JDBC 2.0 types. With full Oracle JDBC 2.0/JDK 1.2 driver availability, we expect that
SQLJ support will be extended to all JDBC 2.0 SQL types, with the interface java.sql.SQLData playing a similar role as
oracle.sql.CustomDatum described in section 3.

641
 ([SORLWLQJ-DYD2EMHFWV &RPSRQHQWV

oracle.sql.NUMBER number;
oracle.sql.NUMBER no = new oracle.sql.NUMBER(7902);
#sql { SELECT COMM INTO :number FROM EMP WHERE EMPNO = :no };
if (number == null) {
System.out.println(“Commission is NULL”);
} else {
System.out.println(“Commission is:” + number.doubleValue());
}
)LJXUH8VLQJRUDFOHVTO180%(5LQ64/-

&86720,=,1*64/'$7$7<3(6
2UDFOH·V64/-WUDQVODWRUDVZHOODVWKH2UDFOH-'%&GULYHUVXSSRUWDPHFKDQLVPWKDWSHUPLWVXVHUVWRIXOO\FXVWRPL]H
WKHZD\LQZKLFKDQoracle.sqlGDWXPLVUHDGIURPRUZULWWHQWRWKHGDWDEDVHIRUPRUHGHWDLOVVHHDOVR>@,QHIIHFW
XVHUVFDQSURYLGHWKHLURZQFXVWRPL]HGZUDSSHUVIRUUHDGLQJDQGZULWLQJ64/GDWD7KHVHZUDSSHUVLPSOHPHQWWKH
CustomDatumLQWHUIDFHVGHVFULEHGEHORZ
&86720'$780,17(5)$&(6
$OOGDWDWKDWLVSDVVHGWRRUIURPWKHGDWDEDVHLVLQIRUPRIDQoracle.sql.Datum $XVHUZLOOEHSURYLGLQJKHURZQ
FXVWRPL]HG-DYDGDWDWKURXJKLPSOHPHQWLQJWKHCustomDatumLQWHUIDFH,QRUGHUWRVHQGDCustomDatumWRWKHGDWDEDVH
LWPXVWEHFRQYHUWLEOHWRDQoracle.sql.Datum YLDDSXEOLFtoDatum()PHWKRG

interface oracle.sql.CustomDatum
{
oracle.sql.Datum toDatum();
}
)LJXUHRUDFOHVTO&XVWRP'DWXPLQWHUIDFH

$GGLWLRQDOO\JLYHQDQDSSURSULDWHoracle.sql.Datum ZHQHHGWREHDEOHWRFRQVWUXFWDQLQVWDQFHRIWKHXVHU·V
CustomDatum7KLVSURSHUW\LVFDSWXUHGLQWKHcreatePHWKRGRIWKHoracle.sql.CustomDatumFactory LQWHUIDFH

interface oracle.sql.CustomDatumFactory
{
oracle.sql.CustomDatum create(oracle.sql.Datum d);
}
)LJXUHRUDFOHVTO&XVWRP'DWXP)DFWRU\LQWHUIDFH

:HVWLOOKDYHWRFRQQHFWERWKRIWKHVHLQWHUIDFHV:HGRVRE\UHTXLULQJWKDWWKHXVHU·VLPSOHPHQWDWLRQRIWKHCustomDatum
LQWHUIDFHDOVRSURYLGHDFRUUHVSRQGLQJCustomDatumFactory ZKLFKPD\EHREWDLQHGE\WKHVWDWLFPHWKRG
public static oracle.sql.CustomDatumFactory getFactory();

0RVWOLNHO\ZUDSSHUVLPSOHPHQWLQJWKLVLQWHUIDFHZLOOEHXVHGLQFRQMXQFWLRQZLWKDQoracle.sql.STRUCT LQWKHFDVHRI
2EMHFW7\SHVDQoracle.sql.REF DQ64/UHIHUHQFHWRDQ2EMHFW7\SHRUDQoracle.sql.ARRAY IRU64/YDUUD\V
DQGQHVWHGWDEOHVWKLVLVGHWDLOHGLQVHFWLRQ
+RZHYHULWFDQRFFDVLRQDOO\EHXVHIXOWRSURYLGHFXVWRPL]HGZUDSSHUVIRURQHRUPRUHRIWKHRWKHUW\SHVDVZHOO6XFK
ZUDSSHUVPLJKWEHXVHGIRUH[DPSOH
• WRSHUIRUPHQFU\SWLRQDQGGHFU\SWLRQRIGDWD

2
OracleTypes refers to oracle.jdbc.driver.OracleTypes. The first four typecodes in the table are identical to corresponding
values in java.sql.Types. They are, respectively, Types.NUMERIC, Types.CHAR, Types.DATE, and Types.BINARY.
3
There is one caveat: types associated with SQL names, such as STRUCT, REF, and ARRAY, represent weak types, and may not be
used as OUT or INOUT host variables in stored procedures, functions, or PL/SQL blocks.
4
For pedagogical purposes we omit two minor details in these interfaces. Read on to discover them.
5
Since interfaces cannot declare static methods, we could not list this requirement in the CustomDatum interface.
641
 ([SORLWLQJ-DYD2EMHFWV &RPSRQHQWV

• WRSHUIRUPYDOLGDWLRQRIGDWD
• WRSHUIRUPORJJLQJRIYDOXHVWKDWKDYHEHHQUHDGRUDUHEHLQJZULWWHQ
• WRSDUVHFKDUDFWHUFROXPQVHJFKDUDFWHUILHOGVFRQWDLQLQJ85/LQIRUPDWLRQLQWRVPDOOHUFRPSRQHQWVRUWRPDS
FKDUDFWHUVWULQJVLQWRQXPHULFFRQVWDQWV
• WRSHUIRUPPDSSLQJRIGDWDHJD'$7(ILHOGLQWRPRUHGHVLUDEOH-DYDIRUPDWVHJjava.util.Date 
• WRVHULDOL]HDQGGHVHULDOL]H-DYDREMHFWVLQWRDQGRXWRI5$:ILHOGVHWF
:HZLOOH[SDQGRQWKHODVWEXOOHWDQGVKRZKRZXVHUVFDQGHILQHDFXVWRPL]DWLRQIRU5$:FROXPQVWKDWSURYLGHVDXWRPDWLF
VHULDOL]DWLRQDQGGHVHULDOL]DWLRQRI-DYDREMHFWV
(;$03/(6(5,$/,=$7,212)-$9$2%-(&76
7KHXVHU·VFODVVLVFDOOHGSerializableDatum DQGGHILQHGLQWKHILOHSerializableDatum.java 7KHSURJUDPXVHV
FODVVHVIURPjava.iojava.sqloracle.sqlDQGoracle.jdbc.driver KRZHYHUZHGRQRWH[SOLFLWO\VKRZWKH
LPSRUWVWDWHPHQWVKHUH7KHVNHOHWRQRIWKLVSURJUDPIROORZVWKHCustomDatumLQWHUIDFHRXWOLQHGDERYH

public class SerializableDatum implements CustomDatum

{
&OLHQWBPHWKRGVBIRUBFRQVWUXFWLQJBDQGBDFFHVVLQJBWKHB-DYDB2EMHFW
public Datum toDatum(OracleConnection c) throws SQLException
{
,PSOHPHQWDWLRQBRIBtoDatum
}

public static CustomDatumFactory getFactory()

{
return FACTORY;
}
private static final CustomDatumFactory FACTORY =
,PSOHPHQWDWLRQBRIBDBCustomDatumFactory BIRUBSerializableDatum ;

&RQVWUXFWLQJBSerializableDatum BIURPBoracle.sql.RAW
public static final int _SQL_TYPECODE = OracleTypes.RAW;
}
)LJXUH6NHOHWRQRI6HULDOL]DEOH'DWXPFODVV

+HUHWKHgetFactoryPHWKRGVLPSO\UHWXUQVDVWDWLFPHPEHUWKDWLPSOHPHQWVWKHCustomDatumFactory LQWHUIDFH:H
DOVRQRWLFHWKDWWKHtoDatumPHWKRGRQWKHCustomDatumLQWHUIDFHDFWXDOO\WDNHVDQ2UDFOH-'%&FRQQHFWLRQDVDQ
DUJXPHQWWKLVLVQHFHVVDU\WRHQVXUHSURSHUW\SHFKHFNLQJDQGFRQYHUVLRQIRUQDPHGW\SHVDWUXQWLPHZHJORVVHGRYHUWKLV
GHWDLOLQ)LJXUH
7KHGHFODUDWLRQDERYHFRQWDLQVDQDGGLWLRQDOILHOG_SQL_TYPECODEGHVLJQDWLQJWKHDFWXDOoracle.sqlW\SHWKDWZHH[SHFW
WRUHDGDQGZULWH7KH64/-WUDQVODWRUH[SHFWVWKHW\SHFRGHWREHSUHVHQWDQGHPSOR\VLWWRGHWHUPLQHFRPSDWLELOLW\EHWZHHQ
WKHXVHUVSHFLILHG-DYDW\SHDQGWKH64/W\SHLQWKHGDWDEDVH7KHVHFRGHVDVZHOODVDGGLWLRQDOLQIRUPDWLRQUHTXLUHGLQ
FHUWDLQFDVHVDUHDOVRXVHGE\WKH-'%&UXQWLPH
1H[WZHSURYLGHWKHGHILQLWLRQVRIWKHFOLHQWPHWKRGVIRUFUHDWLQJDSerializableDatum SRSXODWLQJLWZLWKD-DYDREMHFW
DQGUHWULHYLQJD-DYDREMHFW

&OLHQWBPHWKRGVBIRUBFRQVWUXFWLQJBDQGBDFFHVVLQJBWKHB-DYDB2EMHFW
private Object m_data;
public SerializableDatum() { m_data = null; }
public void setData(Object data){ m_data = data; }
public Object getData() { return m_data; }

641
 ([SORLWLQJ-DYD2EMHFWV &RPSRQHQWV

)LJXUH&OLHQWPHWKRGVRI6HULDOL]DEOH'DWXP

7KHLPSOHPHQWDWLRQRItoDatumPXVWUHWXUQDVHULDOL]HGUHSUHVHQWDWLRQRIWKHREMHFWLQWKHm_dataILHOGDVDQ
oracle.sql.RAW LQVWDQFH<RXZLOOVHHWKHZHOONQRZQVWHSVUHTXLUHGIRUVHULDOL]DWLRQRID-DYDREMHFW$RAWFDQ
LPPHGLDWHO\EHFRQVWUXFWHGIURPDbyteDUUD\

,PSOHPHQWDWLRQBRIBtoDatum

try {
ByteArrayOutputStream os = new ByteArrayOutputStream();
ObjectOutputStream oos = new ObjectOutputStream(os);
oos.writeObject(m_data); oos.close();
return new RAW(os.toByteArray());
} catch (Exception e){
throw new SQLException("SerializableDatum.toDatum: "+e.toString());
}
)LJXUH6HULDOL]LQJD-DYDREMHFWWRDQRUDFOHVTO5$:

,QWKHRSSRVLWHGLUHFWLRQZHPXVWSURJUDPWKHFRQYHUVLRQRIDQoracle.sql.RAW LQVWDQFHWRD-DYDREMHFW1RZZHKDYH
WRSHUIRUPGHVHULDOL]DWLRQVWHSV5DWKHUWKDQMXVWUHWXUQDQObjectZHFRQVWUXFWDQHZLQVWDQFHRISerializableDatum
ZLWKWKHdataILHOGLQVWDQWLDWHG

&RQVWUXFWLQJBSerializableDatum BIURPBoracle.sql.RAW 

private SerializableDatum(RAW raw) throws SQLException {
try {
InputStream rawStream = new ByteArrayInputStream(raw.getBytes());
ObjectInputStream is = new ObjectInputStream(rawStream);
data = is.readObject();
is.close();
} catch (Exception e) {
throw new SQLException("SerializableDatum.create: "+e.toString());
} }
)LJXUH&RQVWUXFWLQJDQLQVWDQFHRI6HULDOL]DEOH'DWXPIURPRUDFOHVTO5$:

)LQDOO\ZHDGGWKHODVWSX]]OHSLHFHWRWKHSURJUDPE\SURYLGLQJDQLPSOHPHQWDWLRQLQVWDQFHRIWKHCustomDatumFactory
LQWHUIDFH:HFUHDWHWKHLPSOHPHQWDWLRQLQIRUPRIDQDQRQ\PRXVFODVV

,PSOHPHQWDWLRQBRIBDBCustomDatumFactory BIRUBSerializableDatum
new CustomDatumFactory() {
public CustomDatum create(Datum d, int sqlCode)
throws SQLException
{
if (sqlCode != _SQL_TYPECODE)
{
throw new SQLException("SerializableDatum: invalid SQL type "+sqlCode);
}
return (d == null) ? null : new SerializableDatum((RAW)d);
} }
)LJXUH,PSOHPHQWDWLRQRI&XVWRP'DWXP)DFWRU\

1RWHWKDWZHSUHYLRXVO\RPLWWHGWKHIDFWWKDWCustomDatumFactory.create WDNHVDVHFRQGDUJXPHQWRIW\SHintZLWK
WKH-'%&W\SHFRGHRIWKHoracle.sql.Datum :HDOVRVHHLQWKLVH[DPSOHKRZWKLVFRGHLVXVHGIRUW\SHFKHFNLQJ
:HFRQFOXGHWKHH[DPSOHE\GHPRQVWUDWLQJKRZWKHXVHUGHILQHGW\SHFDQEHLPPHGLDWHO\XVHGLQDQ64/-SURJUDP7KH
GLVSOD\EHORZVKRZVWKHFUHDWLRQRIDWDEOHZLWKDRAWFROXPQ7KHFRUUHVSRQGLQJ64/-FRGHIUDJPHQWLQVHUWVD-DYDREMHFW

641
 ([SORLWLQJ-DYD2EMHFWV &RPSRQHQWV

LQWKHSDUWLFXODUH[DPSOHDQDUUD\RIObjectLQWRWKLVWDEOH

CREATE TABLE PERSDATA (NAME VARCHAR2(20) NOT NULL, INFO RAW(2000));

SerializableDatum pinfo = new SerializableDatum();
pinfo.setData(new Object[] { “Some objects”, new Integer(51), new Double(1234.27) });
String pname = “MILLER”;
#sql { INSERT INTO PERSDATA VALUES( :pname, :pinfo) };
)LJXUH,QVHUWLQJD6HULDOL]DEOH'DWXPLQWRDWDEOH

:HFDQDOVRFUHDWHDQLWHUDWRUIRUWUDYHUVLQJ3(56'$7$WKDWUHWXUQVDSerializableDatum FROXPQ,WHUDWRUGHILQLWLRQ
DQGWUDYHUVDOFRQVLVWVRIWKHIROORZLQJVWHSV
 'HFODUDWLRQRIDQLWHUDWRUW\SH+HUHZHGHFODUHPersIterDQDPHGLWHUDWRUW\SHZLWKWKHFROXPQVnameDQGinfo
 'HILQLWLRQRIDQLWHUDWRULQVWDQFH:HFDOOLWpcurLQRXUH[DPSOH
 $VVLJQLQJWKHUHVXOWRIDTXHU\WRWKHLWHUDWRULQVWDQFH6LQFHZHXVHGDQDPHGLWHUDWRUWKHELQGLQJRIFROXPQVZLOOEH
SHUIRUPHGE\QDPHDQGWKHFROXPQRUGHULQWKHTXHU\GRHVQRWPDWWHU
 7UDYHUVLQJWKHURZVRIWKHTXHU\UHVXOWYLDWKHnext()PHWKRG7KHYDOXHVRIWKHFROXPQVnameDQGinfoDUHDYDLODEOH
WKURXJKFRUUHVSRQGLQJDFFHVVRUPHWKRGVRQWKHLWHUDWRUpcur

#sql iterator PersIter (SerializableDatum info, String name);

…
PersIter pcur;
#sql pcur = { SELECT * FROM PERSDATA WHERE info IS NOT NULL };
while (pcur.next())
{
System.out.println(“Name:” + pcur.name() + “Info:”+ pcur.info());
}
)LJXUH8VLQJ6HULDOL]DEOH'DWXPLQDQLWHUDWRU

)URPWKHSRLQWRIYLHZRI64/-DSerializableDatum PD\EHXVHGLQ64/-FRGHZKHQHYHUWKHW\SH5$:LVH[SHFWHG
LQ64/7KLVH[DPSOHDOVRH[KLELWVWKHIROORZLQJOLPLWDWLRQVLQUHDGLQJDQGZULWLQJ-DYDREMHFWV:HPD\H[FHHGWKHVL]HRIWKH
RAWFROXPQLQWRZKLFKZHZULWH0RUHRYHU-DYDPXVWDOVRVHULDOL]HDOOREMHFWVUHIHUHQFHGE\WKHREMHFWFRQWDLQHGLQ
SerializableDatum.m_data 7KXVLI-DYDREMHFWVDUHVKDUHGPDQ\FRSLHVRIWKHPPD\DFWXDOO\EHGHVHULDOL]HG/DWHU
ZKHQUHWULHYLQJWKHVHULDOL]HGGDWDEDFNWR-DYDVKDULQJZLOOKDYHEHHQEURNHQ,QWKHVHFDVHVLWLVEHWWHUWRPRGHOREMHFWV
GLUHFWO\LQ64/VXFKDVZLWKWKH2UDFOH2EMHFW7\SHVDQG5()VWKDWDUHGHVFULEHGLQWKHQH[WVHFWLRQ
38%/,6+,1*64/2%-(&77<3(6$1'&2//(&7,21672-$9$
:HEULHIO\VXUYH\2EMHFW7\SHV5()VDQG&ROOHFWLRQ7\SHVLQ2UDFOHDQGH[DPLQHKRZXVHUVPD\FUHDWH-DYDZUDSSHUVIRU
WKHVHW\SHV2UDFOHSURYLGHVWKH-3XEOLVKHUWRROVLPLODULQIXQFWLRQDOLW\WRWKH2EMHFW7\SH7UDQVODWRUIRU&IRUDXWRPDWLQJ
PXFKRIWKHHIIRUWLQFUHDWLQJWKHFRUUHVSRQGLQJ-DYDGHFODUDWLRQVIRUWKHVHW\SHV:HGRJLYHH[DPSOHVRIXVLQJ-3XEOLVKHU
DVZHOODVRIHPSOR\LQJWKHJHQHUDWHG-DYDW\SHVLQ64/-SURJUDPV
2%-(&77<3(6
$QREMHFWW\SHLVVLPLODUWRD64/QDPHGURZW\SHDQGFRQVLVWVRIRQHRUPRUHDWWULEXWHVWKDWGHILQHWKHVWUXFWXUHRIDQ
REMHFW2EMHFWVDUHXVHIXOZKHQUHSUHVHQWLQJUHDOZRUOGHQWLWLHVZKLFKPD\KDYHDFRPSOH[VHWRIDWWULEXWHV2QFHDQREMHFWLV
FUHDWHGLWFDQEHVWRUHGLQRUDFFHVVHGIURPUHODWLRQDOWDEOHVDVHDVLO\DVDQ\RIWKHEDVLF64/GDWDW\SHVVXFKDVD180%(5
RU&+$57KH64/GHFODUDWLRQLQWKHGLVSOD\EHORZGHILQHVWKH2EMHFW7\SH3(56216XEVHTXHQWO\WKHFRQVWUXFWRU
3(5621LVLQYRNHGRQWKHDWWULEXWHYDOXHVRIWKHW\SHWRFUHDWHDQHZREMHFWLQVWDQFHRI3(5621W\SH
CREATE TYPE PERSON AS OBJECT
( FIRSTNAME VARCHAR2(15),

6
Oracle8 Object Types actually constitute an extension of SQL3 Named Row Types. They may have member methods or functions that
model the behavior of an object. Since the Java publishing mechanism currently ignores these methods, we will also not deal with them
in this paper.
641
 ([SORLWLQJ-DYD2EMHFWV &RPSRQHQWV

LASTNAME VARCHAR2(30),
BIRTHDAY DATE
);
CREATE TABLE EMPS (PERS PERSON, EMPNO INTEGER, SAL NUMBER(7,2));
DECLARE P PERSON;
BEGIN
P := PERSON(‘Albert’, `Einstein’, TO_DATE(‘14-MARCH-1879’));
INSERT INTO EMPS VALUES(P, 1001, 5000.0);
END;
)LJXUH'HFODULQJDQGLQVWDQWLDWLQJWKHW\SH3(5621

38%/,6+,1*-$9$:5$33(56)25 2%-(&77<3(6
64/2EMHFW7\SHYDOXHVDUHPDWHULDOL]HGLQ-DYDDVLQVWDQFHVRIWKHFODVVoracle.sql.STRUCT $STRUCTFRQWDLQVDILHOG
valuesZKLFKLVDQDUUD\ZLWKHOHPHQWVRIW\SHoracle.sql.Datum KROGLQJWKHDFWXDOYDOXHVRIDOORIWKHDWWULEXWHVRIWKH
2EMHFW7\SH
*LYHQWKLVLQIRUPDWLRQZHFRXOGQRZJRDKHDGDQGPDQXDOO\ZULWHDCustomDatumZUDSSHUIRUDJLYHQ64/2EMHFW7\SH
+RZHYHUWKLVHQGHDYRULVEHWWHUOHIWWRDWRRO-3XEOLVKHU7KH-3XEOLVKHULVJLYHQ64/2EMHFW7\SHVDQGFUHDWHVWKHVRXUFH
FRGHIRUDFRUUHVSRQGLQJ-DYDZUDSSHUFODVVHV7KHDWWULEXWHVRIWKH64/W\SHFDQEHPDWHULDOL]HGLQRQHRIWZRVW\OHV
 WKHGHIDXOW-'%&PDSSLQJIURP64/W\SHVWR-DYDW\SHVRU
 WKHoracle.sqlUHSUHVHQWDWLRQ
:HKDYHWRFRPPXQLFDWHWR-3XEOLVKHUWKHQDPHVRIZUDSSHUFODVVHVWKDWDUHWREHJHQHUDWHGDVZHOODVWKH64/2EMHFW
7\SHVIURPZKLFKWKH\RULJLQDWH7KLVLVDFFRPSOLVKHGYLDDW\SHILOHWKDWLVSDVVHGWR-3XEOLVKHU7KHV\QWD[RIWKHHQWULHVLQWKH
W\SHILOHLVTYPE64/7\SH!AS-DYD7\SH!,QWKHH[DPSOHZHUHTXHVWWKDWWKHZUDSSHUFODVVEHFDOOHGMyPerson
&RQWHQWVRIWKHILOH types.in:
TYPE PERSON AS MyPerson

&RPPDQGOLQHLQYRFDWLRQRI-3XEOLVKHU
jpub -user=scott/tiger -typefile=types.in
)LJXUH,QYRFDWLRQRI-3XEOLVKHUIRUWKH2EMHFW7\SH3(5621

-3XEOLVKHUZLOOQRZJHQHUDWHWZRILOHVMyPerson.javaZLWKWKH-DYDZUDSSHUIRU3(5621REMHFWVDQG
MyPersonRef.java ZLWKWKH-DYDZUDSSHUIRUVWURQJO\W\SHG5()VWR3(5621%HORZZHVKRZWKHFRQWHQWRI
MyPerson.java DIWHUUHPRYLQJLPSOHPHQWDWLRQGHWDLOV7KHVHFRQGILOHZLOOEHH[DPLQHGLQWKHQH[WVHFWLRQZKHUHZH
GLVFXVV5()W\SHV
public class MyPerson implements CustomDatum
{
public static final String _SQL_NAME = "SCOTT.PERSON";
public static final int _SQL_TYPECODE = OracleTypes.STRUCT;
public static CustomDatumFactory getFactory( ) { … }
public Datum toDatum(OracleConnection c) throws SQLException { … }
…
public String getFirstname() throws SQLException { … }
public void setFirstname(String first_name) throws SQLException { … }
public String getLastname() throws SQLException { … }
public void setLastname(String last_name) throws SQLException { … }
public java.sql.Timestamp getBirthday() throws SQLException { … }
public void setBirthday(java.sql.Timestamp birthday) throws SQLException { … }
}
)LJXUH-3XEOLVKHUJHQHUDWHG-DYDFODVVIRU3(5621

6HYHUDOREVHUYDWLRQVDUHQRWHZRUWK\DERXWWKLVFRGH
 )URPRXUGLVFXVVLRQRIWKHCustomDatumLQWHUIDFHFRPSRQHQWVWKHPHWKRGVgetFactory()DQGcreate()DVZHOO
DVWKH_SQL_TYPECODEILHOGVKRXOGDOUHDG\EHIDPLOLDU2EMHFW7\SHYDOXHVDUHPDWHULDOL]HGDVoracle.sql.STRUCT
LQVWDQFHVDQGZHVSHFLI\WKHFRUUHVSRQGLQJW\SHFRGHOracleTypes.STRUCT :HGRHQFRXQWHUWKHDGGLWLRQDOILHOG
_SQL_NAMEFRQWDLQLQJWKHIXOO64/QDPHRIWKH2EMHFW7\SHWKDWLVHQFDSVXODWHGKHUH$W64/-WUDQVODWLRQWLPHWKLV
641
 ([SORLWLQJ-DYD2EMHFWV &RPSRQHQWV

LQIRUPDWLRQLVQHFHVVDU\LQRUGHUWRSHUIRUPW\SHFKHFNLQJDJDLQVWWKHGDWDEDVH$GGLWLRQDOO\WKH64/W\SHQDPHPD\EH
UHTXLUHGLQFHUWDLQVLWXDWLRQVDWUXQWLPHVXFKDVZKHQDQ287SDUDPHWHURIDVWRUHGSURFHGXUHRUD3/64/EORFNPXVW
EHUHJLVWHUHGZLWK-'%&
 7KHDWWULEXWHVDUHUHSUHVHQWHGWKURXJKDFFHVVRUgetWHUDQGsetWHUPHWKRGV7KLVSURYLGHVIRUPRUHHQFDSVXODWLRQDQG
IOH[LELOLW\DVFRPSDUHGWRDUHSUHVHQWDWLRQYLDILHOGV
 $OODFFHVVRUVFDQUDLVHDQSQLException7KLVSHUPLWVIRUH[DPSOHWKH-DYDZUDSSHUFRGHWRIODJDQH[FHSWLRQ
ZKHQHYHUDQDWWHPSWLVPDGHWRUHWULHYHDSULPLWLYHLHQRQREMHFW-DYDW\SHVXFKDVintWKDWZDVUHDGDVDQ64/
18//)RU-DYDREMHFWVZHFDQDOZD\VPDS-DYDnullWR64/18//
 7KH64/W\SHVKDYHEHHQPDSSHGWRWKHLU-'%&FRXQWHUSDUWV9$5&+$5LVUHSUHVHQWHGDVStringDQG'$7(DV
java.sql.Timestamp 7KLVLVWKH-'%&RU-DYDQDWLYHPDSSLQJ%\SURYLGLQJDGLIIHUHQWYDOXHIRU-3XEOLVKHU·V
FRPPDQGOLQHRSWLRQ´-mappingµZHFRXOGKDYHUHTXHVWHGWKH2UDFOHQDWLYHPDSSLQJZKHUHDOO64/W\SHVZLOOEH
SURGXFHGDVLQVWDQFHVRIFRUUHVSRQGLQJoracle.sqlFODVVHV,QRXUH[DPSOH9$5&+$5ZRXOGEHUHSUHVHQWHGDV
oracle.sql.CHAR DQG'$7(DVoracle.sql.DATE ,QWKLVUHSUHVHQWDWLRQ18//LQIRUPDWLRQLVSUHVHUYHGVLQFHDOO
DWWULEXWHVDUH-DYDREMHFWV)XUWKHUPRUHWKLVPDSSLQJLVIXOO\LQIRUPDWLRQSUHVHUYLQJVLQFHLWLVEDVHGRQWKHLQWHUQDO
E\WHUHSUHVHQWDWLRQRIWKH64/GDWD
 7KHMyPersonFODVVKDVDSXEOLFFRQVWUXFWRUZLWKRXWDUJXPHQWV1RWVKRZQKHUH
 $OWKRXJKQRWVKRZQLQWKHFRGHIUDJPHQWDERYHFRQYHUVLRQVIURPoracle.sqlW\SHVWR-'%&W\SHVDUHRQO\
SHUIRUPHGDVQHHGHG7KLVSURYLGHVDSHUIRUPDQFHHQKDQFHPHQWLQPDQ\FDVHV
 8VHUVPD\ILQGWKHGLIIHUHQWPDSSLQJVW\OHVLQVXIILFLHQWDQGPLJKWSUHIHUWRXVHWKHLURZQFXVWRPL]HGPDSSLQJ7KLVLV
DOVRDFFRPPRGDWHGE\-3XEOLVKHUZLWKDVSHFLDOJHQHUDWLRQPRGHLQWKHW\SHILOH)RUH[DPSOH-3XEOLVKHUFDQJHQHUDWH
RQH-DYDFODVVIRUWKH64/W\SH3(5621VXFKDVPersonWrapperEXWXVHDQRWKHU-DYDFODVVVD\MyPerson,
ZKHUHYHUD3(5621RFFXUVLQRWKHU64/W\SHV7KHXVHUWKHQSURYLGHVWKHFXVWRPL]HGLPSOHPHQWDWLRQRIMyPerson
E\VXEFODVVLQJPersonWrapper
 8VHUVDUHDOVRDEOHWRVSHFLI\FXVWRPL]HGDWWULEXWHQDPHVLQWKHW\SHILOH
,WLVQRZVWUDLJKWIRUZDUGWRXVHWKHMyPersonW\SHLQ64/-SURJUDPV:HDOVRFUHDWHWKHVWRUHG64/IXQFWLRQ%'$7(WKDW
ZLOOEHFDOOHGE\WKH64/-FRGH

$QHZ64/IXQFWLRQWKDWWDNHVD3(5621DUJXPHQW
CREATE FUNCTION BDATE(P PERSON) RETURN DATE AS
BEGIN RETURN P.BIRTHDAY; END;

MyPerson p;
#sql { SELECT PERS INTO :p FROM EMPS WHERE EMPNO = 1001 };
System.out.println(“The name is:” + p.getFirstname() + “ “ + p.getLastname());
java.sql.Date d;
#sql d = { VALUES( BDATE(:p)) };
System.out.println(“The birth date returned by BDATE is:” + d);
)LJXUH8VLQJWKH0\3HUVRQZUDSSHULQ64/-FRGH

,QWKLVH[DPSOHZHXVHMyPerson LQD6(/(&7,172FODXVHDQGDVDVWRUHGIXQFWLRQDUJXPHQW1RWHWKDWZKHQHYHU64/-
SHUIRUPVRQOLQHFKHFNLQJGXULQJSUHFRPSLODWLRQWKLVLVWXUQHGRQE\SDVVLQJWKH´-userµRSWLRQWRWKHWUDQVODWRULWZLOO
YHULI\WKDWWKH64/W\SH6&2773(5621LVSHUPLWWHGZKHUHYHUZHDUHXVLQJDMyPersonKRVWYDULDEOHLQDQ64/
VWDWHPHQW

5()6
$Q2UDFOH5()W\SHLVDSHUVLVWHQWVWURQJO\W\SHGREMHFWUHIHUHQFHGHILQHGLQ64/7KHUHDUHGLIIHUHQWNLQGVRI5()VWKRVH
ZLWKV\VWHPJHQHUDWHGJOREDOO\XQLTXH,GVVFRSHG5()VDQGXVHUGHILQHGFRQVWUXFWRUVZKLFKDOORZGDWDEDVHXVHUVWRVXSSO\
DSULPDU\NH\LQVWHDGRIWKH52:,'LQWRWKH5()VWUXFWXUH
:KHQHYHU-3XEOLVKHUXQSDUVHVDQ64/2EMHFW7\SHDQGJHQHUDWHVD-DYDZUDSSHU-DYD&ODVV!LWDOVRDXWRPDWLFDOO\JHQHUDWHVD
FRUUHVSRQGLQJZUDSSHU-DYD&ODVV!RefWRHQFDSVXODWHDVWURQJO\W\SHG64/5()WKDWFDQUHIHUHQFHLQVWDQFHVRIWKDW2EMHFW
7\SH,QWKHH[DPSOHWKDWZHGLVFXVVHGSUHYLRXVO\-3XEOLVKHUFUHDWHGDQDGGLWLRQDOILOHMyPersonRef.java 7KHFRQWHQWRI
641
 ([SORLWLQJ-DYD2EMHFWV &RPSRQHQWV

WKLVILOHDIWHUUHPRYLQJLPSOHPHQWDWLRQGHWDLOVLVVKRZQEHORZ

public class MyPersonRef implements CustomDatum

{ public static final String _SQL_BASETYPE = "SCOTT.PERSON";
public static final int _SQL_TYPECODE = OracleTypes.REF;
public Datum toDatum(OracleConnection c) throws SQLException { … }
public static CustomDatumFactory getFactory() { … };

public MyPersonRef() { … }
public MyPerson getValue() throws SQLException { … }
public void setValue(MyPerson c) throws SQLException { … }
}
)LJXUH-3XEOLVKHUJHQHUDWHG-DYDFODVVIRU5()3(5621

$VH[SHFWHGWKLVFODVVLPSOHPHQWVWKHCustomDatumLQWHUIDFHZLWKWKHtoDatum()DQGgetFactory()PHWKRGVDQGWKH
_SQL_TYPECODE ILHOG7KHW\SHFRGHIRU5()VLVOracleTypes.REF ,QVWHDGRID_SQL_NAMEILHOGKRZHYHUZHQRZ
VHHD_SQL_BASETYPEILHOGWKDWKROGVWKHQDPHRIWKH2EMHFW7\SHWKDWLVEHLQJUHIHUHQFHGE\WKLV5()
2QFHDMyPersonRefLQVWDQFHUHSUHVHQWLQJD5()WR3(5621KDVEHHQUHWULHYHGIURPDQ2UDFOHGDWDEDVHWKHYDOXHRI
WKHUHIHUHQFHGREMHFWFDQEHREWDLQHGZLWKWKHPHWKRGgetValue()&RQYHUVHO\WKHUHIHUHQFHGREMHFWFDQEHDVVLJQHGD
GLIIHUHQW3(5621YDOXHZLWKsetValue(QHZBYDOXH)1RWHWKDWHDFKRIWKHVHFDOOVLVVHQWGLUHFWO\WRWKHGDWDEDVH7KXV
oracle.sql.REF VSRVVHVVDSXUHO\YDOXHEDVHGVHPDQWLFV
1RWHWKDWZHFDQQRWFUHDWH5()·VWRLQGLYLGXDOWDEOHFROXPQVVXFKDVWKH3(56FROXPQRIWKH(036WDEOHLQRXUH[DPSOH
DERYH7KXVLQWKHVDPSOHFRGHEHORZZHPXVWILUVWFUHDWHDQH[WHQWWDEOHRI3(5621EHIRUHZHFDQPDQLSXODWH5()VWR
3(5621LQ64/-

64/FRGHWRSUHSDUHDQH[WHQWWDEOH
CREATE TABLE PERSON_EXT OF PERSON;
INSERT INTO PERSON_EXT VALUES(PERSON(‘Albert’, ‘Einstein’, TO_DATE(‘14-MARCH-1879’)));

MyPersonRef pref;
#sql { SELECT REF(p) INTO :pref FROM PERSON_EXT p WHERE p.LASTNAME = ‘Einstein’ };
MyPerson p = pref.getValue();
System.out.println(“Birthday:” + p.getBirthday() );
p.setFirstname(“Hans Albert”); p.setBirthday(new java.sql.Timestamp(04, 04, 14, 0, 0, 0));
pref.setValue(p);
java.sql.Date d;
#sql { SELECT p.BIRTHDAY INTO :d FROM PERSON_EXT p WHERE p.LASTNAME = ‘Einstein’ };
System.out.println(“Birthday:” + d );
)LJXUH8VLQJ0\3HUVRQ5HILQ64/-FRGH

&2//(&7,216
&ROOHFWLRQVFDQEHYLHZHGDVGDWDW\SHVJURXSHGLQDFHUWDLQZD\7KH\FDQEHDWWULEXWHVRIREMHFWVRUHOHPHQWVRIDUHODWLRQDO
WDEOH
$YDUUD\LVDQRUGHUHGVHWRI]HURRUPRUHHOHPHQWVRIWKHVDPHW\SHLQFOXGLQJDXVHUGHILQHG2EMHFW7\SH(DFKHOHPHQWKDV
DSRVLWLRQWKDWXQLTXHO\LGHQWLILHVWKHHOHPHQWLQWKHYDUUD\$SRVLWLRQLVDQLQWHJHUUDQJLQJIURPWRWKHPD[LPXPGHFODUHG
QXPEHURIHOHPHQWVLQWKHYDUUD\
$QHVWHGWDEOHLVDRQHFROXPQWDEOHWKDWFDQEHWUHDWHGDVDGDWDW\SHVXFKDVDQREMHFW180%(5RU9$5&+$5,WFDQ
EHDQDWWULEXWHRIDQREMHFWRUEH¶QHVWHG·LQWRDFROXPQRIDUHODWLRQDOWDEOH$QHVWHGFXUVRULVXVHGWRLWHUDWHWKURXJKWKHURZV
RIDQHVWHGWDEOH7KLVPD\EHXVHIXOZKHQLWLVWRRFXPEHUVRPHWRUHWULHYHDQHQWLUHQHVWHGWDEOH
$QDORJRXVO\WRWKH2EMHFW7\SHFDVH-3XEOLVKHUFDQDOVRFUHDWH-DYDZUDSSHUFODVVHVIRUYDUUD\DQGQHVWHGWDEOHW\SHV%RWK
RIWKHVH64/W\SHVDUHUHSUHVHQWHGLQ-DYDDVoracle.sql.ARRAY 7KHJHQHUDWHGCustomDatumFODVVFRQWDLQVWKH64/
W\SHQDPHLQWKH_SQL_NAMEILHOG$OVRQRWHWKDWYDUUD\VDQGQHVWHGWDEOHVFDQQRWEHUHIHUHQFHGE\64/5()V
&RQVHTXHQWO\-3XEOLVKHUZLOOQRWJHQHUDWHDQ\5()ZUDSSHUVIRUWKHVHW\SHV

641
 ([SORLWLQJ-DYD2EMHFWV &RPSRQHQWV

$VPHQWLRQHGSUHYLRXVO\-DYDZUDSSHUFODVVHVPD\EHXVHGLQ64/-VWDWHPHQWVZKHUHYHUWKHFRUUHVSRQGLQJ64/W\SHVRFFXU
LQ64/)RUEUHYLW\ZHRPLWWKH64/-FRGHH[DPSOHVIRUYDUUD\VDQGQHVWHGFODVVHVKHUH
1HVWHGFXUVRUVGRQRWFRQVWLWXWH64/GDWD5DWKHUWKH\UHSUHVHQWUHVXOWVHWV7KH\FDQEHPDWHULDOL]HGLQ64/-HLWKHUDVD
-'%&UHVXOWVHWRULQDVWUXFWXUHGPDQQHUDVQDPHGRUSRVLWLRQHG64/-LWHUDWRULQVWDQFHV
&21&/86,21
7KLVSDSHUFKDUWVDJDWHZD\EHWZHHQ64/DQG-DYDREMHFWV,WLQWURGXFHVDQHIILFLHQW64/GDWDUHSUHVHQWDWLRQLQ-DYDZLWKWKH
oracle.sqlSDFNDJH7KHCustomDatumLQWHUIDFHPHFKDQLVPPDSV64/GDWDWRXVHUGHILQHG-DYDW\SHV:HLOOXVWUDWHWKH
XVHIXOQHVVRICustomDatumWKURXJKDQH[DPSOHZKHUHSerializable-DYDREMHFWVDUHVWRUHGLQ5$:GDWDEDVHFROXPQV
:HDOVRVKRZWKDWWKHVDPHPHFKDQLVPLVXVHGIRUPDSSLQJ64/REMHFWW\SHV5()VDQGYDUUD\QHVWHGWDEOHW\SHVWR-DYD
)LQDOO\ZHH[DPLQHKRZWKH-3XEOLVKHUWRROJHQHUDWHV-DYDZUDSSHUVIRU64/W\SHVDQGKRZWKHVHW\SHVDUHVXEVHTXHQWO\
XVHGLQ64/-SURJUDPV
64/-RIIHUVVHYHUDODGYDQWDJHVRYHU-'%&,WSURYLGHVPXFKPRUHFRQFLVHV\QWD[IRUHPEHGGLQJVWDWLF64/LQ-DYD0RUH
LPSRUWDQWO\LWRIIHUVDKHDGRIWLPHFKHFNLQJRI64/V\QWD[DQGVHPDQWLFVDWWUDQVODWLRQWLPHUDWKHUWKDQUXQWLPH7\SH
FKHFNLQJEHWZHHQ64/W\SHVDQG-DYDW\SHVLVSHUIRUPHGZLWKDQRQOLQHGDWDEDVHFRQQHFWLRQDQGLVSDUWLFXODUO\XVHIXOZKHQ
SURJUDPPLQJZLWKVWUXFWXUHG64/W\SHV5()VDQGYDUUD\VQHVWHGWDEOHV7KHCustomDatumPHFKDQLVPIRUPDSSLQJ64/
GDWDWR-DYDSURYLGHVWKHQHFHVVDU\VXSSRUWIRUVWDWLFW\SHFKHFNLQJ
$GGLWLRQDOO\DOOXVHUGHILQHG-DYDW\SHVWKDWZUDS64/W\SHVFDQEHXVHGWUDQVSDUHQWO\LQ64/-SURJUDPVDVLIWKH\ZHUH
´EXLOWLQµ-'%&W\SHV&RQWUDVWWKLVZLWKFRUUHVSRQGLQJ2UDFOH-'%&SURJUDPVZKHUHXVHUVPD\KDYHWRXVH2UDFOHVSHFLILF
PHWKRGVDVZHOODVSURYLGLQJFDVWVIURP-'%&UHVXOWVHWVDQGVWDWHPHQWVWRWKHLU2UDFOHVSHFLILFLPSOHPHQWDWLRQV$OOWKLVLV
HQFDSVXODWHGLQWKH64/UXQWLPHSURYLGHGZLWK2UDFOH
1RWHWKDW\RXQHHGQRWFKRRVHEHWZHHQHLWKHU64/-RU-'%&<RXFDQXVHERWKRIWKHVHIXOO\FRPSOHPHQWDU\DQG
LQWHURSHUDEOH$3,VWRJHWKHU7KHLUEDVLFHIILFLHQW64/GDWDUHSUHVHQWDWLRQLVWKHVDPH7KHLUPHFKDQLVPIRUPDSSLQJ64/
GDWDWRXVHUGHILQHG-DYDW\SHVIRU2EMHFW7\SHV5()VYDUUD\VQHVWHGWDEOHVDQGRWKHU64/W\SHVLVWKHVDPH7KH
-3XEOLVKHUWRROLVHTXDOO\XVHIXOIRU64/-DQG-'%&SURJUDPPHUV7KXVXVHUGHILQHGGDWDUHSUHVHQWDWLRQVFDQEHXVHGZLWK
ERWKG\QDPLF64/VWDWHPHQWVLQ-'%&DVZHOODVZLWKVWDWLFVWDWHPHQWVLQ64/-
2UDFOHLFRQQHFWV-DYDDQG64/SURJUDPPLQJLQDQXQSUHFHGHQWHGZD\<RXDUHZHOFRPHGWRWUDYHOWKHH[FLWLQJ2EMHFWURDG
PDSSHGRXWKHUHEHWZHHQWKHVHWZRODQJXDJHV
$&.12:/('*0(176
7KLVSDSHULVEDVHGRQWKHZRUNRIWKH64/-DQG-'%&WHDPVDW2UDFOH,ZRXOGOLNHWRWKDQN-XOLH%DVX%ULDQ%HFNHU
5DJDPD\L%K\UDYDEKRWOD5DNHVK'KRRSDU3LHUUH'XIRXU6DOPDQ.KDQ3UDEKD.ULVKQD7KRPDV.XULDQ$ODQ37KLHVHQ
-HUU\6FKZDU]DQG%ULDQ:ULJKWIRUWKHLUFRQWULEXWLRQVDQGFRPPHQWV
5()(5(1&(6
>@$Q2YHUYLHZRI64/-(PEHGGHG64/LQ-DYD-XOLH%DVX2UDFOH2SHQ:RUOG
>@'HYHORSLQJ-DYD$SSOLFDWLRQVZLWK2UDFOH2EMHFWV3UDEKD.ULVKQD2UDFOH2SHQ:RUOG
>@2UDFOHL64/--'%&DQG-3XEOLVKHUXVHUGRFXPHQWDWLRQ2UDFOH&RUSRUDWLRQ

641