Comunitat DSTSC

1. Introducció

Aquest document pretén ser una guia per a desenvolupar aplicacions web basades en Framework de la DIBA de 2012 i alineades amb el prototipus d’exemple FAM.
Aquestes normes estan ordenades segons la importància i agrupades per tipologia. Cadascuna d’elles tindrà un codi identificador o tag.

2. Normativa d’entorn

2.1. Ús de SVN

• DIBA_REV [SVN Comments]: Cal posar comentaris en cada pujada al SVN i aquests han de començar amb el codi de projecte i dos punts. Aquestes pujades han de ser preferiblement atòmiques respecte del desenvolupament / desenvolupaments que s’hagin fet.

• DIBA_REV [SVN Ignored]: No s’ha de modificar la configuració dels recursos inclosos / exclosos del control del SVN.

2.2. Desplegament per entorns

• DIBA_REV [Filter]: Cal generar els war en funció de l’entorn al que es vol desplegar l’aplicació. Per fer això cal compilar executant els launch de Maven que s’incorporen a l’entorn i que ja estan configurats per llançar els profiles corresponents del pom.xml. Amb aquests profiles es garanteix que s’usa el fitxer de propietats corresponents i que es deixa el war al directori local que toca.

2.3. Ús de Maven

• DIBA_REV [Maven]: Cal usar el Maven correctament (dependències enlloc de jars dins del projecte...).

2.4. Generació de Releases

• DIBA_REV [Releases]: S’ha de generar versions de Release quan convingui i intentar, sempre que sigui possible, no instar una versió que no ho sigui a Producció Aquestes han de tenir la seva carpeta al SVN i configurada al pom.xml, i ha de seguir el format:

http://svn.corpo.ad.diba.es:8080/subversion/[codi_prj]/releases

3. Normativa de codificació

3.1. Arquitectura de classes

• DIBA_REV [Architecture Packages]: Cal respectar la nomenclatura de packages i l’agrupació de classes en packages seguint l’estil definit al FAM, així com incloure l’arxiu package-info.java de cadascun d’ells.

• DIBA_REV [Architecture Entites]: Cal configurar les entitats i els seus atributs i anotacions de la mateixa manera que al FAM.

Documentació relacionada: FWK_Mapeig_BBDD.doc

• DIBA_REV [Architecture DAOS]: Cal respectar la jerarquia de les classes / interfícies de DAOS.

Documentació relacionada: Estructura_FWK.pdf – DAOS

• DIBA_REV [Architecture Services]: Cal respectar la jerarquia de les classes / interfícies de Services.

Documentació relacionada: Estructura_FWK.pdf – Services

• DIBA_REV [Architecture BB]: Cal respectar la jerarquia de les classes / interfícies de Beans, ja siguin BB d’entitat, de sessió, de popup...

Documentació relacionada: Estructura_FWK.pdf – Beans

• DIBA_REV [Architecture Properties]: Cal carregar i tractar de la mateixa que al FAM els fitxers de propietats.

Documentació relacionada: FWK_FAM_Properties

• DIBA_REV [Architecture Transactions]: Cal gestionar les connexions a BD i transaccions de la mateixa que al FAM.

• DIBA_REV [Utilities WebUtils]: Cal usar la funcionalitat de la classe WebUtils i no replicar-la en altres classes.

• DIBA_REV [Utilities FormatUtils]: Cal usar la funcionalitat de la classe FormatUtils i no replicar-la en altres classes.

• DIBA_REV [Utilities FileUtils]: Cal usar la funcionalitat de la classe FileUtils i no replicar-la en altres classes.

• DIBA_REV [Utilities AppUtils]: Cal usar la classe AppUtils per a posar les utilitats pròpies de l’aplicació.

• DIBA_REV [Constants AppConstants]: Cal usar la classe AppConstants per a posar les constants generals per l’aplicació i per a canviar els valors per defecte de les que venen amb la base si és necessari.

3.2. Control d’errors i sortida dels logs

• DIBA_REV [Exceptions DibaException]: Cal usar la funcionalitat de la classe DibaException per a gestionar les excepcions.

Documentació relacionada: FWK_FAM_Missatges.

• DIBA_REV [LOG AppMessage]: Cal usar la classe AppMessage i les propietats appMessages.properties per a la construcció dels missatges.

Documentació relacionada: FWK_FAM_Missatges.

• DIBA_REV [Exceptions handleException]: Cal usar handleException de la classe AbstractDibaBB per a gestionar els missatges per pantalla.

Documentació relacionada: FWK_FAM_Missatges.

• DIBA_REV [LOG dibaLogClass]: Les classes han de tenir els objectes de LOG igual que al FAM (snippet dibaLogClass de l’Eclipse).

Documentació relacionada: FWK_FAM_Missatges.

• DIBA_REV [LOG dibaLogMethod]: El mètodes han de tenir log d’inici i de fi igual que al FAM (snippet dibaLogMethod de l’Eclipse). Així com altres logs que puguin ser d’interès.

Documentació relacionada: FWK_FAM_Missatges.

3.3. Qualitat de la codificació

• DIBA_REV [QA Delete]: No han d’existir classes o funcions que no s’usin en cap part del codi (a excepció de les classes base o classes d’utilitats).

• DIBA_REV [QA CheckStyle]: Cal revisar el report de CheckStyle i corregir els errors i els warnings que sigui fàcilment corregibles (l’objectiu no és 0 warnings).

Documentació relacionada: FWK_Documentació_Site.doc

• DIBA_REV [QA PMD]: Cal revisar el report de PMD i corregir els errors greus, errors i els warnings que sigui fàcilment corregibles (l’objectiu no és 0 warnings).

Documentació relacionada: FWK_Documentació_Site.doc

• DIBA_REV [QA FindBugs]: Cal revisar el report de FindBugs i corregir els errors i els warnings que sigui fàcilment corregibles (l’objectiu no és 0 warnings)

Documentació relacionada: FWK_Documentació_Site.doc

• DIBA_REV [QA FIXME PROJECTE]: Cal ajustar les referències al FAM al nostre projecte, estan representades pels FIXME PROJECTE.

Documentació relacionada: FWK_Crear_Nou_Projecte_BackOffice.doc

• DIBA_REV [Combos]: la gestió dels elements de tipus combo ha de fer-se seguint l’exemple del FAM: per als combos dels detalls la gestió s’ha de fer en les funcions entityToForm i formToEntity fent referència a un objecte d’aquell tipus que està instanciat en el BB.

I en canvi per a les combos de filtre de llistats s’haurà de tenir un objecte de tipus List dins de la classe del xxxlistModule, amb el booleà corresponent indicant si està habilitat o no si es tracta de combos anidades. Aquests objectes de llista seran omplerts des de la corresponent classe xxxService i l’entitat que estigui continguda en el combo haurà d’implementar la interfície DibaSelectItem que obliga a tenir el parell id – descripció.

• DIBA_REV [M&D]: Per als llistats mestre – detall, sempre que es pugui s’haurà de seguir un dels dos exemples que s’inclouen en el FAM:

• Materialitats a BBDD: Comanda – Línea, recomanats per aquells llistats en que la relació és 1:N.
• Gestionats a memòria: Ubicació – Activitat, recomanats per aquells llistat en que la relació és N:M i tan sols serveixen per establir la relació, però no per donar d’alta nou elements.

• DIBA_REV [QA Tasks]: Cal eliminar, o tenir clar perquè hi són, totes les tasques tipus FIXME o TODO.

• DIBA_REV [QA Code]: Aquest tag està destinat a un ús genèric per tal de mostrar qualsevol aspecte relacionat amb la codificació que hagi de ser revisat i que no tingui una categoria pròpia.

• DIBA_REV [Bug]: Aquest tag està destinat a un ús genèric per tal de mostrar qualsevol error en la codificació que hagi de ser revisat i que no tingui una categoria pròpia.

3.4. Estils i presentació

• DIBA_REV [Style]: Sempre que existeixi un estil corporatiu per un botó, taula,camp de text, icona... que s’adequa al que es vol, s’ha d’utilitzar aquest abans de fer-ne un de nou a l’aplicació. El nous i específics de l’aplicació han d’estar en fitxer aplicacio.css.

• DIBA_REV [Navigation]: Sempre que es pugui s’ha de seguir la gestió de la navegació basada amb les constants del core NavigationConstants. Quan no es pugui s’ha de simular el mateix funcionament en una classe anàloga al projecte. I sempre que des de una funció d’un BB es pugui modificar l’string de sortida per una altra funció, aquest pas intermedi ha d’estar controlar amb la funció checkNavigateToError de la classe abstracte AbstractDibaBB de la que hereten tots els BB.

• DIBA_REV [Literals]: Sempre que existeixi un literal al fitxer literalsCore.properties que s’adequa al que es vol, s’ha d’utilitzar aquest abans de fer-ne un de nou a l’aplicació. El nous i específics de l’aplicació han d’estar en fitxer literalsApp.properties. No s’han de posar mai textos directament en els fitxers .jspx

3.5. Tests unitaris

• DIBA_REV [UnitTests]: Si hi ha test unitaris han de funcionar correctament en el moment de generar els .wars de Desenvolupament i Preproducció.

Documentació relacionada: FWK_Desplegament_projecte_eclipse.doc.

3.6. Pujada de fitxers al servidor FTP

• DIBA_REV [FTP]: S’ha de garantir l’atomicitat entre les transaccions a la BBDD i les pujades de fitxers al FTP tal i com es fa al FAM (informant primer la data de baixa per després posar-la a null).

3.7. Nomenclatura

• DIBA_REV [NC Class]: S’ha de seguir les convencions de noms que hi ha al FAM per a les classes: xxxService, xxxDao, xxxServlet, xxxBB, xxxListModule, PopupxxxBB, SuggestxxxBB, xxxDTO, xxxSearchFilter, Defaultxxx, [codi_project]xxx per a entitats...

• DIBA_REV [NC Method]: S’ha de seguir les convencions de noms que hi ha al FAM per als mètodes.

• DIBA_REV [NC JSF]: S’ha de seguir les convencions de noms que hi ha al FAM per a les .jspx: pxxxDetall, pxxxLlista, pxxxPopupyyy, pxxxDetallyyy, pxxxDetallyyys...

• DIBA_REV [NC English]: S’ha escollit com a principal llenguatge per a la definició de les classes, els seus mètodes, atributs... l’anglès. També hi ha algunes parts en català. S’hauria d’intentar que això seguís en aquesta línia.