CUBA Platfrm. Develper s Manual Preface This manual prvides the reference infrmatin fr the CUBA platfrm and cvers the mst imprtant tpics f develping business applicatins with it. Intended Audience This manual is intended fr applicatin develpers using the CUBA platfrm. The fllwing technlgies knwledge is required t use the platfrm: Java Standard Editin Relatinal databases (SQL, DDL) Further Reading This manual and ther dcumentatin related t the CUBA platfrm can be fund at www.cubaplatfrm.cm/manual. Vide materials and presentatins that can help yu t understand the platfrm are available at www.cubaplatfrm.cm/tutrials. Yu can als check ut nline dem applicatins at www.cuba-platfrm.cm/nline-dem. Knwledge f the fllwing technlgies and framewrks will be helpful t get a deeper understanding f the platfrm: Gradle build system Spring Framewrk Java Persistence API EclipseLink framewrk Vaadin web applicatins framewrk HTML / CSS / JavaScript Java Servlets Java Swing Feedback If yu have any suggestins fr imprvement f this Manual, please cntact supprt at www.cubaplatfrm.cm/supprt/tpics.
If yu find a mistake in the dcumentatin, please specify the number f the chapter and attach a small prtin f the surrunding text t facilitate the search. 1. Intrductin This chapter prvides infrmatin abut the CUBA platfrm features and requirements. 1.1. Overview CUBA platfrm is an ideal tl fr develpment teams wrking n line-f-business applicatins, typically having extensive data mdel, hundreds f screens and cmplex business lgic. Based n a mainstream technlgy stack, CUBA platfrm brings unparalleled prductivity by utilizing a rich set f ready t use data-aware cmpnents, extensive scafflding, visual interface designer and ht deply. Open architecture allws a develper t custmize any part f the framewrk, prviding high levels f cntrl and flexibility. Develpers have the freedm t use ppular Java IDEs and have full access t the surce cde. CUBA applicatins fit seamlessly int the crprate IT envirnment, supprting majr databases and applicatin servers, as well as ppular apaas cluds. Streamlined clustered deplyment ensures scalability and failver, while a generic REST API enables easy integratin with ther systems. 1.2. Technical Requirements Minimum requirements fr develpment using CUBA platfrm: Memry 4 GB Hard drive space 5 GB Operating system: Micrsft Windws, Linux r Mac OS X 1.3. Release Ntes CUBA platfrm changelg is available at http://files.cuba-platfrm.cm/cuba/platfrm/platfrm-6.0- changelg.html. 2. Installatin and Setup Minimum sftware requirements are as fllws: Java SE Develpment Kit (JDK) 8. It is recmmended that yu use Oracle Java HtSpt VM. In rder t build and run prjects utside Studi, yu need t set the path t the JDK rt directry in the JAVA_HOME envirnment variable, e.g. C:\Prgram Files\Java\jdk1.8.0_60. On Windws, yu can d this at Cmputer Prperties Advanced System Settings Advanced Envirnment variables. The value f the variable shuld be added t the System variables list. Java IDE: IntelliJ IDEA Cmmunity Editin 13+ r Eclipse 4.3+. We recmmend using IntelliJ IDEA.
In the mst basic scenari, the built-in HyperSQL (http://hsqldb.rg) can be used as the database server. This is sufficient fr explring the platfrm capabilities and applicatin prttyping. Fr building prductin applicatins, it is recmmended t install and use ne f the full-featured DBMS supprted by the platfrm, like PstgreSQL fr instance. The web interface f the platfrm-based applicatins supprts all ppular brwsers, including Ggle Chrme, Mzilla Firefx, Safari, Opera 15+, Internet Explrer 9+, Micrsft Edge. 2.1. CUBA Studi Installatin Prerequisites: Make sure that Java SE Develpment Kit (JDK) 8 is installed by running the fllwing cmmand in the cnsle: java -versin The cmmand shuld return the Java versin, e.g. 1.8.0_60. If yu cnnect t the internet via a prxy server, sme Java system prperties must be passed t the JVM running Studi and Gradle. These prperties are explained here: http://dcs.racle.cm/javase/8/dcs/techntes/guides/net/prxies.html (see prperties fr HTTP and HTTPS prtcls). It is recmmended t set these prperties system-wide in the JAVA_OPTS envirnment variable. The Studi launch script passes JAVA_OPTS t the Java executable. In rder t install CUBA Studi, take the fllwing steps: 1. Dwnlad an apprpriate installer r ZIP archive frm https://www.cuba-platfrm.cm/dwnlad. 2. Run the installer r unzip the archive t a lcal directry, e.g. c:/wrk/studi 3. Launch the installed applicatin r pen the cmmand line, g t bin directry and run studi 4. In the CUBA Studi Server windw, enter the fllwing parameters: Java hme JDK installatin t be used fr building and running prjects. If yu have set the JAVA_HOME envirnment variable as described in the beginning f this chapter, it will appear in this field. Otherwise, Studi will try t find yur Java installatin itself. Gradle hme leave this field empty; in this case, the required Gradle distributin will be dwnladed autmatically. If yu want t use a lcal Gradle distributin, enter the path t the respective directry in the field. Fr prject build system t wrk crrectly, Gradle 2.6 is required. Server prt CUBA Studi server prt (the default prt is 8111). IDE prt IDE plugin listening prt (the default prt is 48561). Repsitry binary artifacts repsitry URL and authenticatin parameters.
5. The fllwing ptins are als available: Check fr updates - check fr new versins n every start. Help language - built-in help language. Offline - enable wrking with prjects withut an Internet cnnectin, prvided that all the required libraries have been previusly dwnladed frm the repsitry. Send annymus statistics and crash reprts - enable Studi t send errr statistics t develpers. Enable remte cnnectin - by default, it is assumed that Studi runs n lcalhst. Select this checkbx if yu need t cnnect t this Studi instance frm a remte hst. 6. Click Start t run the Studi server. The server will dwnlad, run, and cnnect t the Gradle daemn. This may take a significant amunt f time n first startup; n subsequent launches, this will take just a few secnds. After that, the web server will be started, and the URL f the Studi interface will appear in the URL field. By clicking, yu can pen the address in yur default web brwser; by clicking Cpy yu can cpy the address t the clipbard. 7. Open the specified address in the web brwser. 8. In the Studi web interface, click Create new t create a new prject, r Imprt t add an existing ne t the Recent list. 9. Once the prject is pened, the Studi will dwnlad the surce cde f the platfrm base prjects and save it t the lcal flder. Befre building the prject, it is recmmended t wait until the dwnlad is finished and make sure that the backgrund task indicatr in the bttm left crner has faded ut. 2.2. IDE Integratin Take the fllwing steps t integrate Studi with IntelliJ IDEA r Eclipse:
1. Open r create a new prject in the Studi. 2. Switch t Prject prperties sectin and click Edit. Select the required Java IDE by checking IntelliJ IDEA r Eclipse. 3. Select Build > Create r update <IDE> prject files in the Studi menu. The crrespnding files will be created in the prject directry. 4. Fr IntelliJ IDEA integratin: a. Run IntelliJ IDEA 13+ and install CUBA Framewrk Integratin plugin, frm the plugin repsitry: File > Settings > Plugins > Brwse Repsitries. 5. Fr Eclipse integratin: a. Run Eclipse 4.3+, pen Help > Install New Sftware, add http://files.cubaplatfrm.cm/eclipse-update-site repsitry and install the CUBA Plugin. b. In the CUBA sectin f the Windw > Preferences menu, check Studi Integratin Enabled, and click OK. Please nte that IDE: n prt 48561 label has appeared in the bttm left crner f the Studi. Nw the crrespnding surce cde files will be pened in IDE when yu click IDE buttns in the Studi. 3. Quick Start This sectin describes the prcess f creating an applicatin using CUBA Studi. Similar infrmatin is prvided in the vides available at www.cuba-platfrm.cm/quickstart. Make sure that the necessary sftware is already installed and set up n yur cmputer, see Installatin and Setup. Key stages f ur applicatin develpment: 1. Data mdel develpment including creatin f entities describing applicatin dmain and crrespnding database tables. 2. Develpment f the user interface screens enabling t create, view, update and delete data mdel entities. 3.1. Applicatin Details The applicatin shuld maintain infrmatin abut the custmers and their rders. A custmer has the fllwing attributes: Name E-mail Order attributes: Ownership by a custmer Date Amunt The applicatin UI shuld cntain:
Custmers brwser screen; Custmer editr screen, cntaining as well the list f this custmer s rders; General rders brwser screen; Order editr screen. The applicatin shuld supprt user interface in English and Russian. 3.2. Creating a Prject 1. Start CUBA Studi and pen its web interface (See CUBA Studi Installatin). 2. Click Create new. 3. Specify the name f the new prject in the Prject name field f the New prject windw fr example, sales. The name shuld cntain nly Latin letters, numbers and underscres. Think carefully n the prject name at this stage, as changing it later n will require cmplex manual interventin. 4. The fllwing fields belw will be autmatically ppulated: Prject path the path t the new prject directry. Yu can select the directry manually by clicking the buttn next t the field. The Select flder windw will appear with the list f flders n yur hard drive. Yu can select ne f thse, r create a new directry by clicking the + buttn. Prject namespace the namespace which will be used as a prefix fr entity names and database tables. The namespace can cnsist f Latin letters nly and shuld be as shrt as pssible. Fr example, if the prject name is sales_2, the namespace can be sales r sal. Rt package the rt package f Java classes. It can be adjusted later, but the classes generated at prject creatin will nt be mved. Base prjects versin the platfrm versin used in the prject. The platfrm artifacts will be autmatically dwnladed frm the repsitry n prject build. 5. Click OK. Empty prject will be created in the specified sales directry and the main Studi windw will pen. 6. Assemble the prject: select ptin Build > Assemble prject in the Studi main menu. At this stage all required libraries will be dwnladed and prject artifacts will be assembled in build subdirectries f the mdules. 7. Create the database n the lcal HyperSQL server: select ptin Run > Create database in the menu. The database name is the same as prject namespace by default. 8. Select Run > Deply menu ptin. Tmcat server with the deplyed applicatin will be installed in the prject build subdirectry. 9. Select Run > Start applicatin server ptin. The link next t the Web applicatin captin in the status panel will becme available in a few secnds s yu will be able t pen the applicatin directly frm Studi. The username and passwrd are admin / admin. The running applicatin cntains tw main menu items (Administratin and Help), as well as security and administratin subsystems functinality. 3.3. Creating Entities
Let us create the Custmer entity class. G t the Entities tab in the navigatin sectin and click New entity. The New entity dialg windw will appear. Enter the name f the entity class Custmer in the Class name field. Click OK. The entity designer page will be displayed in the wrkspace.
The entity name and the database table name will be autmatically generated in the Name and the Table fields respectively. Leave the existing value StandardEntity - in the Parent class field. Leave the Inheritance strategy field blank. Click buttn next t the Name t pen the Lcalized message windw. Specify lcalizatin fr the entity name fr the available languages in it. Next, let us create entity attributes. T d this, click the New buttn belw the Attributes table. Create attribute windw will appear. Enter the name f the entity attribute name, in the Name field. Select DATATYPE value in the Attribute type list, specify String attribute type in the Type field and then set the length f the text attribute t 100 characters in the Length field. Check the Mandatry bx. The name f the database table clumn will be autmatically generated in the Clumn field.
Nw click buttn next t the attribute name t pen the Lcalized message windw. Lcalize the attribute name in the available languages. Click Add t add the attribute. email attribute is created in the same way but the value in Length field shuld be set t 50. After creating the attributes, g t the Instance name tab in the entity designer t specify Name pattern. Select the name attribute in the Available attributes list and mve it t the Name pattern attributes list by clicking the buttn with the right arrw n it.
Custmer entity creatin is nw cmplete. Click OK in the tp panel t save the changes and clse the page. Let us create the Order entity. Click New entity ptin n the Entities tab. Enter the Class name Order. The entity shuld have the fllwing attributes: Name custmer, Attribute type ASSOCIATION, Type Custmer, Cardinality MANY_TO_ONE. Name date, Attribute type DATATYPE, Type Date. Check Mandatry bx fr date attribute. Name amunt, Attribute type DATATYPE, Type BigDecimal. Specify lcalized captin fr each f the attributes by clicking the buttn next t the attribute name. 3.4. Creating Database Tables It is sufficient t click Generate DB scripts buttn in Entities tab n the navigatin panel t create database tables. After that, Database scripts page will pen. Bth incremental DB update scripts frm the current state (Update scripts) and initial DB creatin scripts (Init tables, Init cnstraints, Init data) will be generated n this page.
Click Save and clse buttn t save the generated scripts. T run update scripts, stp the running applicatin using the Run > Stp applicatin server cmmand, then select Run > Update database. 3.5. Creating User Interface Screens Nw we will create screens fr custmers and rders data management. 3.5.1. Screens fr Custmer Select Custmer entity in the Entities tab n the navigatin panel t create standard screens fr viewing and editing Custmers. Click Create standard screens link at the bttm f the sectin. After that, Create standard screens page will appear.
All fields in this dialg are already ppulated with default values, there is n need t change them. Click the Create buttn. custmer-edit.xml and custmer-brwse.xml items will appear in GUI Mdule n Screens tab f the navigatin panel. Yu can specify lcalized captins fr the screens. Fr this, select a screen and click Edit t pen the screen designer page. G t the Prperties tab. Click the [] buttn next t the Captin field and specify screen names in different lcales. Alternatively, yu can pen messages.prperties item lcated in the screens package and edit brwsecaptin and editcaptin messages fr available lcales. 3.5.2. Order Screens Order entity has the fllwing distinctin: since ne f the attributes is the Order.custmer reference attribute, yu shuld define a view including this attribute (standard _lcal view des nt include reference attributes).
G t the Entities tab n the navigatin panel, select the Order entity and click the New view buttn. View designer page will pen. Enter rderwithcustmer as the view name, click n custmer attribute and select _minimal view fr the Custmer entity in the panel n the right. Click OK in the tp panel. After that, select the Order entity and click Create standard screens. Select rderwithcustmer in the View fields in bth brwser and editr panels f the Create standard screens page and click Create.
rder-edit.xml and rder-brwse.xml items will appear in the GUI Mdule n the Screens tab f the navigatin panel. Yu can specify lcalized captins fr the Order screens as described abve fr the Custmer screens. 3.5.3. Applicatin Menu At the mment f their creatin, the screens were added t the applicatin menu item f the default applicatin menu. Let us rename it. Switch t the Main menu tab n the navigatin panel and click Edit. The Menu designer page will pen. Select the applicatin menu item t edit its prperties. Enter the new value f the menu identifier shp in the Id field, then click the Captin edit buttn and set lcalized names f the menu item.
After editing the menu, click OK in the tp panel. 3.5.4. Custmer Editr With a List f Orders D the fllwing t display the list f Orders in the Custmers edit screen: G t the Screens tab n the navigatin panel. Chse custmer-edit.xml screen and click Edit. G t the Datasurces tab n the screen designer page and click New. Select the newly created data surce in the list. Its attributes will appear in the right part f the page. Specify cllectindatasurce in the Type field. In Id field enter the data surce identifier rdersds. Select cm.sample.sales.entity.order entity in the Entity list. Select _lcal view in the View list. Enter the fllwing query in the Query field: select frm sales$order where.custmer.id = :ds$custmerds rder by.date The query cntains rders selectin criterin with ds$custmerds parameter. The parameter value named like ds${datasurce_name} will cntain id f the entity selected in datasurce_name datasurce at the mment, in this case it is the id f the Custmer being edited.
Click Apply t save the changes. Next g t the Layut tab in the screen designer and find the Label cmpnent in the cmpnents palette. Drag this cmpnent t the screen cmpnents hierarchy panel and place it between fieldgrup and windwactins. G t the Prperties tab in the prperties panel. Enter msg://rders in the value field. Click the in available languages. buttn next t the value field and define label values
Tip If the applicatin is nt intended t be used in multiple languages, the value in the value field can be entered straight in the required language. Drag Table frm the cmpnents palette t cmpnents hierarchy panel and place it between label and windwactins. Select this cmpnent in the hierarchy and specify table size in prperties n the Layut tab: set 100% in the width field and 200px in the height field. G t the Prperties tab. Set rderstable value as id, chse rderds frm the list f available datasurces.
Click OK in the tp panel t save the changes in the screen. 3.6. Running the Applicatin Nw let us see hw the created screens lk in the actual applicatin. Select Run > Restart applicatin server. Lg in selecting English language in the lgin windw. Open the Sales > Custmers menu item:
Figure 1. The Custmers brwser Click Create: Open the Sales > Orders menu item: Figure 2. The Custmer editr screen
Figure 3. The Orders brwser Click Create: Figure 4. The Order editr