Problem Solution Discussion Writing Library Files

{ print general message plus any database-specific message System.err.println SQLException: + e.getMessage ; System.err.println SQLState: + e.getSQLState ; System.err.println VendorCode: + e.getErrorCode ; } } } } public static void tryQuery Connection conn { Statement s = null; try { issue a simple query s = conn.createStatement ; s.execute USE cookbook; s.close ; print any accumulated warnings SQLWarning w = conn.getWarnings ; while w = null { System.err.println SQLWarning: + w.getMessage ; System.err.println SQLState: + w.getSQLState ; System.err.println VendorCode: + w.getErrorCode ; w = w.getNextWarning ; } } catch SQLException e { print general message plus any database-specific message System.err.println SQLException: + e.getMessage ; System.err.println SQLState: + e.getSQLState ; System.err.println VendorCode: + e.getErrorCode ; } } }

2.4 Writing Library Files

2.4.1 Problem

You not ice t hat youre writ ing sim ilar code for com m on operat ions in several program s.

2.4.2 Solution

Put funct ions t o perform t hose operat ions in a library file. Then you writ e t he code only once.

2.4.3 Discussion

This sect ion describes how t o put code for com m on operat ions in library files. Encapsulat ion or m odularizat ion isnt really a recipe so m uch as a program m ing t echnique. I t s principal benefit is t hat you dont have t o repeat code in each program you writ e; inst ead, you j ust call a funct ion t hat s in t he library. For exam ple, by put t ing t he code for connect ing t o t he cookbook dat abase int o a library funct ion, you need not writ e out all t he param et ers associat ed wit h m aking t hat connect ion. Sim ply invoke t he funct ion from your program and youre connect ed. Connect ion est ablishm ent isnt t he only operat ion you can encapsulat e, of course. Lat er on in t he book, ot her ut ilit y funct ions are developed and placed in library files. All such files, including t hose shown in t his sect ion, can be found under t he lib direct ory of t he recipes dist ribut ion. As you writ e your own program s, youll probably ident ify several operat ions t hat you perform oft en and t hat are good candidat es for inclusion in a library. The t echniques dem onst rat ed in t his sect ion will help you writ e your own library files. Library files have ot her benefit s besides m aking it easier t o writ e program s. They can help port abilit y. For exam ple, if you writ e connect ion param et ers int o each program t hat connect s t o t he MySQL server, you have t o change each program if you m ove t hem t o anot her m achine where you use different param et ers. I f inst ead you writ e your program s t o connect t o t he dat abase by calling a library funct ion, you localize t he changes t hat need t o be m ade: it s necessary t o m odify only t he affect ed library funct ion, not all t he program s t hat use it . Code encapsulat ion also can im prove securit y in som e ways. I f you m ake a privat e library file readable only t o yourself, only script s run by you can execut e rout ines in t he file. Or suppose you have som e script s locat ed in your web servers docum ent t ree. A properly configured server will execut e t he script s and send t heir out put t o rem ot e client s. But if t he server becom es m isconfigured som ehow, t he result can be t hat your script s get sent t o client s as plain t ext , t hus displaying your MySQL usernam e and password. And youll probably realize it t oo lat e. Oops. I f t he code for est ablishing a connect ion t o t he MySQL server is placed in a library file t hat s locat ed out side t he docum ent t ree, t hose param et ers wont be exposed t o client s. Be aware, t hough, t hat if you inst all a library file t o be readable by your web server, you dont have m uch securit y should you share t he web server wit h ot her developers. Any of t hose developers can writ e a web script t o read and display your library file, because by default t he script will run wit h t he perm issions of t he web server and t hus will have access t o t he library. The recipes t hat follow dem onst rat e how t o writ e, for each API , a library file t hat cont ains a rout ine for connect ing t o t he cookbook dat abase on t he MySQL server. The Perl, PHP, and Pyt hon rout ines are writ t en t o ret urn t he appropriat e t ype of value a dat abase handle, a connect ion ident ifier, or connect ion obj ect , or t o exit wit h an error m essage if t he connect ion cannot be est ablished. The error- checking t echniques used by t hese rout ines are t hose discussed in Recipe 2.3 . The Java connect ion rout ine dem onst rat es a different approach. I t ret urns a connect ion obj ect if it succeeds and ot herwise t hrows an except ion t hat t he caller can deal wit h. To assist in handling such except ions, t he library also includes ut ilit y funct ions t hat ret urn or print an error m essage t hat includes t he error inform at ion ret urned by MySQL. Libraries are of no use by t hem selves; t he way t hat each one is used is illust rat ed by a short t est harness program . You can use any of t hese harness program s as t he basis for creat ing new program s of your own: Make a copy of t he file and add your own code bet ween t he connect and disconnect calls. Library file writ ing involves not only t he quest ion of what t o put in t he file, but also subsidiary issues such as where t o inst all t he file so it can be accessed by your program s and on m ult iuser syst em s such as Unix how t o set it s access privileges so it s cont ent s arent exposed t o people who shouldnt see it . Writ ing t he library file and set t ing up your language processor t o be able t o find it are API - specific issues; t heyre dealt wit h in t he language- specific sect ions t o follow. By cont rast , quest ions about file ownership and access m ode are m ore general issues about which youll need t o m ake som e decisions no m at t er which language you use at least if youre using Unix : • I f a library file is privat e and cont ains code t o be used only by you, t he file can be placed under your own account and m ade accessible only t o you. Assum ing a library file m ylib is already owned by you, you can m ake it privat e like t his: chmod 600 mylib • I f t he library file is t o be used only by your web server, you can inst all it in a server library direct ory and m ake t he file owned by and accessible only t o t he server user I D. You m ay need t o be root t o do t his. For exam ple, if t he web server runs as wwwusr , t hese com m ands m ake t he file privat e t o t hat user: • chown wwwusr mylib chmod 600 mylib • I f t he library file is public, you can place it in a locat ion t hat your program m ing language searches aut om at ically when it looks for libraries. Most language processors search for libraries in som e default set of direct ories. You m ay need t o be root t o inst all files in one of t hese direct ories. Then you can m ake t he file world readable: chmod 444 mylib The exam ple program s in t his sect ion assum e t hat youll inst all library files som ewhere ot her t han t he direct ories t he language processors search by default , as an excuse t o dem onst rat e how t o m odify each languages search algorit hm t o look in a direct ory of your choosing. Many of t he program s writ t en in t his book execut e in a web cont ext , so t he library file inst allat ion direct ories used for t he exam ples are t he per l, php, pyt hon, and j ava direct ories under usr local apache lib. I f you want t o put t he files som ewhere else, j ust adj ust t he pat hnam es in t he program s appropriat ely, or else t ake advant age of t he facilit y t hat m any program m ing languages provide for specifying where t o look for library files by m eans of an environm ent or configurat ion variable. For our API languages, t hese variables are list ed in t he following t able: La n gu a ge Va r ia ble n a m e Va r ia ble t ype Per l PERL5LIB Environm ent variable PHP include_path Configurat ion variable Pyt hon PYTHONPATH Environm ent variable Java CLASSPATH Environm ent variable I n each case, t he variable value is a direct ory or set of direct ories. For exam ple, if under Unix I put Perl library files in t he u paul lib perl direct ory, I can set t he