----------------------------------------------------- ProfileManager and ProfileServerManager by MDN ----------------------------------------------------- Author: Marco De Nittis (denittis@sinet.it) Summary: 1. Directory structure 2. Compiling and packaging 3. Libraries used 4. Configuring and running the ProfileManager 5. Configuring and running the ProfileServerManager 6. Database configuration 7. Features 8. References Notes: In this note will be used some abbreviation: PM - ProfileManager PSM - ProfileServerManager MDN - me JCP - Java Comunity Process NIST - National Institute of Standards and Tecnologies ---------------------------------------- 1. Directory structure - / -- src (a) | - lib (b) | - jsp (c) | - conf (d) | - classes (e) * | - dist (e) * | - temp (f) | - log (g) * * Automatically created during compiling/packaging/running a) Contains all the java sources, it has different branches: - src -- it contains package it.polito.cpl.**, it is all the main code of this project (by MDN) |- awtesina contains the classes of the wizard applet (unknown author) |- examples contains all the classes of the proxy (by NIST *) |- tools contains the classes of some tools used by the proxy (es traceviewer) (by NIST) |- gov contains the NIST implementation of JAIN-SIP e JAIN-SDP standards (by NIST) ** |- javax contains the JAIN-SIP e JAIN-SDP standard classes (by JCP) ** * some little modification on examples.proxy.Proxy by MDN ** those packages are not necessary for the build of this project b) Contains all the jar libraries, it also has different directory: - lib - contains the libraries used by the PM and the proxy |- server contains the libraries used by the PSM (and also the PM and proxy) * |- xerces contains the xerces implementation (present in the original NIST distribution) * This directory is present because all the jars contained in are packed in the jsp war for the web app distribution. c) Contains all the jsp and PSM elements: the jsp and html pages, PSM configuration file, web.xml (the web application configuration file) and the profile java template used by the ClassCompilerProfileCodec. d) Contains the configuration files for the proxy and the PM. In particular there is the xml conf file for the proxy (actually polito.xml) and a property conf file for the PM (deafult is profilemanager.conf) e) Here are present all the compiled class file of the project f) Here normally are created temporary java and class files generate by the class compiler (it can be reconfigured in the PSM conf file) g) This directory is automatically created by the NIST proxy for storing its log (the location can be modified in the xml proxy conf file) --------------------------------------- 2. Compiling and packaging For compiling and packaging it's present and ant(2) script (build.xml) for managing all the phases, there are present different targetss: . clean deletes all the object files and dirs . polito compiles the PM and PSM components . proxy compiles the NIST-proxy components . build compiles the PM, the PSM and the proxy (default) . distPM packages all the PM classes in a single archive in the dist directory . distPSM packages all the PM classes in a single archive in the dist directory . distProxy packages all the NIST proxy classes in a single archive in the dist directory . jsp prepares the PSM distribution under the jsp directory with all the needed libs . war packages the war webapp distribution file (PSM) in the dist directory . dist packages all . cleanDist deletes all packaged files . nistLib compiles ths JAIN-SIP implementation (not necessary if the its library jar it's present in the classpath) . distNIST packages all the JAIN-SIP NIST implementation classes in a single archive in the dist directory . buildAll compiles and packages everything All the target are chained to have the complete update. For compiling the components: >ant For packing the PSM war file: >ant war For packing all the components: >ant dist Notes: - It's important for compiling with ant to have the javac compiler in the ant classpath, normally it's stored in: JAVA_HOME/lib/tools.jar - It's necessary to use the JDK 1.4 or greater for compiling the NIST - proxy. --------------------------------------- 3. Lbraries used During compilation are necessaries these libraries: For the NIST-proxy and the PM: - nist-sip.jar containing the JAIN SIP (and JAIN SDP) NIST implementation * - mdnLogger.jar MDN logger classes - jakarta-regexp-xxx.jar regular expression engine from Apache jakarta (3) For the PSM: - mdnLogger.jar MDN logger classes - jakarta-regexp-xxx.jar regular expression engine from Apache jakarta - commons-fileupload.jar Apache jakarta Mime-multipart upload library, used by the jsp pages During the execution are necessary also other libraries, runtime loaded: - JDBC driver for the DBProfileRepository according to the DB used, in the distribution are presents the mysql driver and the hsqldb standalone dbms. For the PSM are also necessary in the classpath the proxy and the JAIN-SIP libraries, these are used only during the profile compiling phase. ---------------------------------------------- 4. Configuring and running the ProfileManager * Configuring Since the PM is a part of the NIST proxy, it's necessary to configure also the proxy, for that I refer back to its documentation. I assume that the correct proxy configuration file is placed in the conf directory (named for instance polito.xml). The PM default configuration file is 'conf/profilemanager.conf', it's possibile to specify a different one using the enviroment variable 'it.polito.cpl.client.conf'. An typical conf file can be: ------------ # Repository it.polito.cpl.repository=it.polito.cpl.DBProfileRepository # Decoder it.polito.cpl.profilecodec=it.polito.cpl.classcompiler.ClassCompilerProfileCodec # ProfileManager cache it.polito.cpl.client.cache.rmienabled=true it.polito.cpl.client.cache.rmiport=1099 it.polito.cpl.client.cache.rmihost=localhost it.polito.cpl.client.cache.maxsize=300 # DBProfileRepository it.polito.cpl.repository.db.driver=com.mysql.jdbc.Driver it.polito.cpl.repository.db.url=jdbc:mysql://localhost/mdn it.polito.cpl.repository.db.user=tesi it.polito.cpl.repository.db.passwd=tesi #Translations it.polito.cpl.addressmatch=0(\\d\\d\\d\\d)@polito.it it.polito.cpl.addresstranslate=sip:0{1}@130.192.31.63:5060;user=phone;phone-context=unknown ------------ * it.polito.cpl.repository It's the classname of the repository used, for DBProfileRepository is it.polito.cpl.DBProfileRepository * it.polito.cpl.profilecodec The class name of the profile codec to install, for ClassCompilerProfile codec is it.polito.cpl.classcompiler.ClassCompilerProfileCodec * it.polito.cpl.client.cache.rmienabled Select to activate the cache rmi interface to update remotely (from the PSM) the cache contents * it.polito.cpl.client.cache.rmiport Select the port where the RMI registry for the cache is running * it.polito.cpl.client.cache.rmihost=localhost Select the host where the RMI registry for the cache is running * it.polito.cpl.client.cache.maxsize=300 Specify the size of the cache it.polito.cpl.addressmatch It's used for setting up the address translation feature, contains the regular expression for address matching it.polito.cpl.addresstranslate Contains the pattern to translate the address if the match is succesfull DBProfileRepository specific: * it.polito.cpl.repository.db.driver=com.mysql.jdbc.Driver Class name of the jdbc driver to use * it.polito.cpl.repository.db.url=jdbc:mysql://localhost/mdn Connect string to use for establishing connection * it.polito.cpl.repository.db.user * it.polito.cpl.repository.db.passwd DB username and password * Running If the cache RMI publishing is activate it's necessary to run also the RMIRegistry before running the proxy. The RMI registry can be used also only by the proxy for registration features (refer to the NIST proxy documentation). The proxy can be execute in two ways: - bare proxy - GUI with traceviewer feature To execute the bare proxy the main class is examples.proxy.Proxy, for the GUI is examples.proxy.gui.ProxyLauncher, in both case is necessary to specify the proxy conf file, so for launching the proxy: >java examples.proxy.Proxy -cf conf/polito.xml for the GUI: >java examples.proxy.gui.ProxyLauncher -cf conf/polito.xml Anyway it's necessary to set up the classpath, it can be done automatically using the SmartLoader in this way: >java -jar SmartLoader.jar examples.proxy.gui.ProxyLauncher -cf conf/polito.xml The SmartLoader starts the application adding to the classpath all the jars present in the current dir and in 'lib' (and also its subdirs) and all the classes present in the current and in the 'classes' directories. ---------------------------------------------- 5. Configuring and running the ProfileServerManager * Configuring The PSM it's not a standalone component, it lives inside an jsp enabled web server (from now called 'appserv') , it can be done including in the appserv the 'jsp' directory, or deploying its packed war archive. The configuration file to use is in the 'jsp' directory and normally it's called 'profileservermanager.conf' (the name is configured inside the web.xml file), it has the same syntax of the PM one. One possible conf file can be: ---- # ProfileServerManager configuration it.polito.cpl.repository=it.polito.cpl.DBProfileRepository it.polito.cpl.profilecodec=it.polito.cpl.classcompiler.ClassCompilerProfileCodec # DBProfileRepository it.polito.cpl.repository.db.driver=com.mysql.jdbc.Driver it.polito.cpl.repository.db.url=jdbc:mysql://localhost/mdn it.polito.cpl.repository.db.user=tesi it.polito.cpl.repository.db.passwd=tesi # ClassCompileProfileCodec it.polito.cpl.codec.classcompiler.outputpath=d:/tesi/work/temp it.polito.cpl.codec.classcompiler.compiler=com.sun.tools.javac.Main it.polito.cpl.codec.classcompiler.preservesources=true it.polito.cpl.codec.classcompiler.template=/ProfileTemplate.java # Remote cache it.polito.cpl.client.cache.rmienabled=true it.polito.cpl.client.cache.rmiport=1099 it.polito.cpl.client.cache.rmihost=localhost ---- The most part is identical to the PM one, with the same meaning for the parameters. It can be seen an another part referring to the codec,in particular: * it.polito.cpl.codec.classcompiler.outputpath The directory where are stored the temporary files created during the compilation phase, this directory MUST exist. * it.polito.cpl.codec.classcompiler.compiler The class name of the compiler used for creating profiles, actually it has been configured to work with the SUN jdk compiler (class com.sun.tools.javac.Main tested with jdk 1.4.1) and the Eclipse (4) compiler (class org.eclipse.jdt.internal.compiler.batch.Main test with 2.1 version). * it.polito.cpl.codec.classcompiler.preservesources Can be true or false, it select if the sources and class files shuold be preserved or deleted (the default behaviour is to delete). * it.polito.cpl.codec.classcompiler.template Contains the path to the profile template file starting from the PSM webapp root. * Running To run the PSM it's necessary to deploy the PSM web app to the appserv, the procedure depends on the server used, basically it can be done in 2 ways, the first is to configure the appserv to use also the jsp directory as web app root. With Tomcat (ver 4.1.24) it can be done adding near the other Context nodes something like this: ---- ---- Modifing according to the local settings the attributes: - displayName (description of the web app) - docBase (local path to the 'jsp' dir) - path (appserv virtual directory to reach the web app from the browser) The second way (and the simpler one) is to use the war packed file with the appserv deploying tool, with tomcat it can be done with the manager webapp via the browser. Note that if something has been modified, also only the configuration file, the web app must be repacked and redeployed again. To access the the ProfileServerManager you have to open a web browser to: http://hostname:8080/PSM/ Where hostname is the name of the host where the appserv is running, with the correct port (8080 is the default for tomcat), to the virtual dir specified during the deploy phase (in tomcat it's visible in the manager page). ** IMPORTANT NOTES ** 1. All the library files used by the PSM are inside the war (or in the 'WEB-INF/lib' dir if you use the unpacked version), but for compiling profiles it's absolutely necessary to add the classpath of the appserv (note: the appserv, NOT the web app) the necessary jars, because of some application server classloader isolation reasons. With all the appserv tested this problem cannot be avoided with some workarounds. The libraries used for compiling profiles are: - nist-sip.jar (present in 'lib') - compileLib.jar (present in 'dist') - mdnLogger.jar (present in 'lib') 2. For validating CPL file correctly it's necessary to put in the appserv main directory the CPL DTD (cpl.dtd) present in the root directory of the distribution. ---------------------------------------------- 6. Database configuration For using the DBProfileRepository as repository class, it's necessary to properly configure the DBMS used. First the table that contains the profile has to be created, it contains 4 fields: - Id as string of at least 50 characters it contains the profile id, if possible it should be the primary key. - Timestamp as bigint, it will contains a java long value (the timestamp) - ProfileObject as blob, it will contain the binary rappresentation of the profile - Cpl as text blob, it will contain the cpl source of the profile Here are present the DDLs relatives to MySQL and HsqlDB DBMS. MySQL DDL CREATE TABLE profiles ( Id varchar(50) NOT NULL default '', Timestamp bigint(11) default NULL, ProfileObject blob, Cpl text, PRIMARY KEY (Id), UNIQUE KEY Id(Id) ) TYPE=MyISAM; HsqlDB DDL CREATE TABLE Profiles ( Id CHAR(50) NOT NULL , Timestamp BIGINT, ProfileObject LONGVARBINARY, Cpl LONGVARCHAR, PRIMARY KEY(Id) ) ---------------------------------------------- 7. Features * Address translation There is a built-in feature that allows to translate a set of addresses directly to different set using regular expressions (it's embedded in the ProfileManager). The configuration is divided in two part: the matching pattern and the translation pattern. The matching pattern is a standard regular expression to which the address of every call is compared, if the matching is succesfull this address is substituted with the translation pattern. For example: matching pattern => sip:.+@sales.company.com (.+ means any string with at least 1 character, so any address in that domain) translation pattern => sip:sales@company.com In this case every call directed to any address in the domain 'sales.company.com' is redirected to the sales@company.com address. It's possible to place in the translated address some elements presents in the original address, this can be done using parenthesis in matching pattern and placeholders in the translation string. A place holder is an element like that '{x}' where x is the number of the brace group in the matching string, so '{1}' is substituted with the contents of the first brackets pair matched, '{2}' with the second and so on... For example: matching pattern => sip:.+@(.+).company.com translation pattern => sip:{1}@company.com That results in: sip:foo@IT.company.com => sip:IT@company.com sip:ceo@marketing.company.com => sip:marketing@company.com I.e. everything that matched the '(.+)' pattern is taken and is placed in the translated address in the position of '{1}' It's possible to use up to 10 parenthesis grouping, moreover the placeholder '{0}' correspond to the whole origin address. -------------------------------------- 8. References 1. NIST - National Institute of Standards and Tecnology http://snad.ncsl.nist.gov/proj/iptel/ 2. Apache Ant project - http://ant.apache.org/ 3. Apache Jackarta project - http://jakarta.apache.org/ 4. Eclipse project - http://www.eclipse.org/