JBoss Administration Server Understanding Deployments and Classloaders .

1. JBoss Administration Server Understanding Deployments and Classloaders.

2. Deployments in JBoss • Deployment is the term used for the process of installing a web application, EJB application , enterprise application or a resource adapter. • Makes it available for the clients to access it. • You can deploy several different types of enterprise applications in JBoss AS: • The WAR application archive (e.g., myapp.war) packages a Java EE web application in a JAR file. It contains servlet, view pages, libraries, and deployment descriptors such as web.xml, faces-config.xml, jboss-web.xml etc. • The EAR application archive (e.g., myapp.ear) packages a Java EE enterprise application in a JAR file. It typically contains a WAR file for the web module, JAR files for EJB modules, as well as deployment descriptors such as application.xml and jboss-app.xml etc. • You can also deploy JAR files containing EJBs or other service objects directly in JBoss AS. • The SAR application archive (e.g., myservice.sar) packages a JBoss service in a JAR file. It is mostly used by JBoss internal services. • The *-ds.xmlfile defines connections to external databases. The data source can then be reused by all applications and services in JBoss AS via the internal JNDI. • You can deploy XML files with MBean service definitions. If you have the appropriate JAR files available in the deploy or lib directories, the MBeans specified in the XML files will be started. This is the way how you start many JBoss AS internal services, such as the JMS queues.

3. EAR Application : Anatomy • Packaging one or more modules into a single archive so that the deployment of the various modules onto an application server happens simultaneously and coherently. J2EE deployment descriptor, application.xml. • Sample application.xml looks like below. • Jboss provides jboss-app.xml for JBoss-specific deployment configuration for the EAR application.For instance, it can specify the deployment order of modules in the EAR, deploy JBoss-specific application modules in the EAR, such as SARs (Service ARchive for MBeans) and HARs (Hibernate ARchive for Hibernate objects), provide security domain and JMX MBeans that can be used with this application, etc. • <application> • <display-name>Example 2 </display-name> • <module> • <web> • <web-uri>example2.war</web-uri> • <context-root>/example2</context-root> • </web> • </module> • </application> <jboss-app> <loader-repository> myapp:archive=myapp.ear </loader-repository> </jboss-app>

4. WAR Application : Anatomy • Root directory contains all the html, jsp, images files and the additional directories containing these files. • In the root directory there is a special directory 'Web-inf' which contains the web deployment descriptor (web.xml), classes and the lib directory. • jboss-web.xml file to add JBoss-specific information in the WEB-INF folder. • Specify resource references, EJB references, specifying security domains etc. • <web-app> • <servlet> • <servlet-name>HelloWorld</servlet-name> • <servlet-class>HelloWorld</servlet-class> • </servlet> • <servlet-mapping> • <url-pattern>/servlet/HelloWorld</url-pattern> • <servlet-name>HelloWorld</servlet-name> • </servlet-mapping> • </web-app> • <jboss-web> • <!-- Use the JaasSecurityMgr other security domain for authentication and authorization of secured web content. --> • <security-domain>java:/jaas/other</security-domain> • </jboss-web>

5. JAR (EJB) Applications - Anatomy • META-INF/ directory can contain the following files: • META-INF/ejb-jar.xml -- the EJB J2EE deployment descriptor for this EJB module. • META-INF/MANIFEST.MF -- an optional file that can be used to specify additional meta-information for the JAR. For example, MANIFEST.MF can be used to extend the CLASSPATH used by the EJB module. • ejb-jar.xml, introduces EJB Bean in the EJB module to the application container. • Classes folder contains the module’s class files. • jboss.xml file to add JBoss-specific information in the META-INF folder. • Contains container specific mappings like queues, Data Sources etc. • <enterprise-beans> • <message-driven> • <ejb-name>TestMDB</ejb-name> • <ejb-class>TestMDB</ejb-class> • </message-driven> • </enterprise-beans> • </ejb-jar> • <jboss> • <enterprise-beans> • <message-driven> • <ejb-name>TestMDB</ejb-name> • <configuration-name>Standard Message Driven Bean</configuration-name> • <destination-jndi-name>/queue/DLQ</destination-jndi-name> • </message-driven> • </enterprise-beans> • </jboss>

6. Service Archive (SAR) : Anatomy • Usage confined to Jboss Application Server and not a J2EE standard. • Used for deploying a service component in the application server without dependent on other components. • When application server starts, these SAR files or independent components will be deployed and starts running independently. • JBoss's service archive architecture is based on the Java Extension Management (JMX). During the server bootup process, the service archive deployer (SARDeployer) instantiates the JBoss service classes and exposes them as manageable beans through JMX.  • In the SAR applications, we create a Mbean interface and the Mbean implementation class. • jboss-service.xmlis the deployment descriptor which contains the references to the classes and this is found in the META-INF folder of SAR Application.\ • <server> • <mbean code="JavaBeat" name="service.javabeat:service=JavaBeat"/> • </server>

7. How to deploy applications in JBoss? • Ways to deploy the applications in Jboss Application Server. • Hot Deployment • Admin Console • JMX Console • Twiddle. • Ant Script

8. Hot Deployment • Hot-deployable services are those which can be added to or removed from the running server. These are placed in the $JBOSS_HOME/server/<instance-name>/deploy directory. • Defined in the jbossAs/server/server-profile/deploy/hdscanner-jboss-beans.xml • The URLDeploymentScannerMBean service provides the JBoss hot deployment capability. This service watches one or more URLs for deployable archives and deploys the archives as they appear or change. It also undeploys previously deployed applications if the archive from which the application was deployed is removed. • The Hot Deployment can be disabled just by removing the hdscanner-jboss-beans.xml from the deploy folder. • You can create custom hot deploy directory by modifying the $JBOSS_HOME/server/$PROFILE/conf/bootstrap/profile.xml <bean name="HDScanner" class="org.jboss.system.server.profileservice.hotdeploy.HDScanner"> <property name="deployer"> <inject bean="ProfileServiceDeployer"/></property> <property name="profileService"> <inject bean="ProfileService"/></property> <property name="scanPeriod">5000</property> <property name="scanThreadName">HDScanner</property> </bean>

9. How to deploy applications in JBoss? • Admin Console: • You can deploy the application from the Jboss Admin Console as well. • Navigate to the Applications  <Type of applications> • Deploy the application in exploded format • or archives (war,jar,ear,rar formats). • When deployed , it copies over the deployment • into the jbossAs/server/server-profile/deploy folder • You can also re-deploy / undeploy the applications • from the Admin console • You can start, stop the application from the Admin Console.

10. How to deploy applications in JBoss? • JMX Console: • Deployment using the JMX console. • Navigate to the “jboss.system” object type • Click on “service=MainDeployer” Mbean. • Now invoke the operation ‘deploy’ by passing the location of the file. Note: There are overloaded deploy methods, invoke the method that takes the “java.net.URL” as an argument type and pass the application location.

11. How to deploy applications in JBoss? • Twiddle: • We can use twiddle utility to deploy, redeploy and undeploy the applications. • Navigate to the $Jboss_Home/bin folder. • For deploying the application. • twiddle.bat -s localhost invoke "jboss.system:service=MainDeployer" deploy "file:/c:/TestMDB.jar" • For re-deploying the application. • twiddle.bat -s localhost invoke "jboss.system:service=MainDeployer" redeploy "file:/c:/TestMDB.jar" • For undeploying the application. • twiddle.bat -s localhost invoke "jboss.system:service=MainDeployer" undeploy "file:/c:/TestMDB.jar"

12. EJB Deployments in JBoss • Client looks up the EJB Bean using the JNDI. • If the bean is deployed in a standalone JAR file in the JBOSS_DIST/default/deploy directory, the bean is accessible via local JNDI name MyBean/local, where MyBean is the implementation class name of the bean as we showed earlier. The "local" JNDI in JBoss AS means that the JNDI name is relative tojava:comp/env/. • If the JAR file containing the bean is packaged in an EAR file, the local JNDI name for the bean ismyapp/MyBean/local, where myapp is the root name of the EAR archive file (e.g., myapp.ear, see later for the EAR packaging of EJB3 beans). Note: Use @Remote for a remote bean and @LocalBinding for a local access. The deployment is done via the JBoss EJB3 deployer in JBOSS_DIST/ server/default/deployers/ejb3.deployer/. The EJB3 deployer automatically scans JARs on the classpath to look for EJB3 annotations. When it finds classes with EJB3 annotations, it would deploy them as EJB3 services.

13. Hibernate in JBoss • Hibernate an open source Java persistence framework project. Perform powerful object relational mapping and query databases using HQL. • The default Hibernate property values are specified in the JBOSS_DIST/server/default/deploy/ejb3.deployer/MEAT-INF/persistence.properties file. Below is the persistence.properties file bundled in JBoss AS 5.0. hibernate.transaction.manager_lookup_class=org.hibernate.transaction.JBossTransactionManagerLookup #hibernate.connection.release_mode=after_statement #hibernate.transaction.flush_before_completion=false

14. Classloaders. • The Java Classloader is a part of the JRE that dynamically loads Java classes into the JVM. Usually classes are only loaded on demand. • Each Java class must be loaded by a class loader. Furthermore, Java programs may make use of external libraries or may itself be composed, at least in part, by a number of libraries. • When the JVM is started, three class loaders are used: • Bootstrap class loader. • The bootstrap class loader loads the core Java libraries (<JAVA_HOME>/lib directory). This class loader, which is part of the core JVM, is written in native code. • Extensions class loader • The extensions class loader loads the code in the extensions directories (<JAVA_HOME>/lib/ext or any other directory specified by the java.ext.dirs system property). It is implemented by the sun.misc.Launcher$ExtClassLoader class. • System class loader • The system class loader loads code found on java.class.path, which maps to the system CLASSPATH variable. This is implemented by thesun.misc.Launcher$AppClassLoader class. Note: You can also write custom class loaders to have more fine grained control over the class loading mechanism.

15. Delegation Model • Delegation model for class loaders was introduced in Java 2. • class loaders are arranged hierarchically in a tree, with the bootstrap class loader as the root of the tree. • Each user-defined class loader is assigned a "parent" class loader when it is constructed. • Log Filter: • Watch for filter criteria of log file, then send notifications • Criteria, eg: • Message severity level • Subsystem generating the message • User ID running the subsystem • Message ID • Message text

16. Jboss VFS ( Virtual File System) Why? • Earlier versions, there was lot of redundancy of the resource handling code scattered/ duplicated. •  It was code that was trying to determine what type of resource a particular resource was, e.g. is it a file, a directory, or a jar loading resources through URLs. • Issues processing of nested archives. • Many problems with file locking on Windows systems, which forced us to copy all hot-deployable archives to another location to prevent locking those in deploy folders. • File locking was a major problem that could only be addressed by centralizing all the resource loading code in one place. • Recognizing a need to deal with all of these issues in one place, wrapping it all into a simple and useful API, we created the VFS project.

17. Jboss VFS ( Virtual File System) What? • Usage in VFS can be split in two pieces: • Simple resource navigation • Visitor pattern API • As mentioned, in plain JDK resource handling navigation over resources is far from trivial. You must always check what kind of resource you're currently handling, and this is very cumbersome.With VFS we wanted to limit this to a single resource type - VirtualFile. • VFS API is its implementation of a proper visitor pattern. This way it's very simple to recursively gather different resources, something quite impossible to do with plain JDK resource loading. Cons. • It adds additional layer on top of JDK's resource handling, meaning extra invocations are always present when you're dealing with resources. • We also keep some of the jar handling info in memory to make it easy to get hold of a specific resource, but at the expense of some extra memory consumption.

18. JBoss ClassLoader • The JBoss ClassLoader framework is made up of a number of abstractions at different levels. • The ClassLoader project is split into 3 subprojects • classloader • classloading • classloading-vfs • The JBoss ClassLoader project is the runtime implementation of the classloader framework. If you just want the basic functionality of the classloader then you can use this level directly. Here you can create ClassLoaderPolicys that define each classloader's rules and link them together to create a peer delegate classloading system. • The JBoss ClassLoading project is the deployment time framework that allows classloaders to be constructed from ClassLoadingMetaData. Rather than dealing with constructing policies and manually linking them together, you specify requirements and capabilities for each ClassLoading Module. The system then links these requirements to capabilities as they are satisifed and checks their consistency. You can think of this level as a kind of dependency injection framework for classloaders. • The VFSClassLoader provides an implementation of the ClassLoaderPolicy using the JBoss Virtual File System project. This can be used directly or in the JBoss ClassLoading framework. • http://community.jboss.org/wiki/JBossClassLoaderIntroduction

19. There are two levels of scoping, isolation from other deployments, and isolation that overrides the loading of JBoss server classes.  With nested modules, only the top level file may specify class loader scoping. If you have a .ear file containing other modules, only scoping specified in the .ear's META-INF/jboss-app.xml is used. This also applies for any other deployment which contains sub-deployments.  For example, if a .sarcontains a .war deployment, only the .sar META-INF/jboss-service.xml scoping has effect.

20. Deploying third party library files. • Third party jars files used are organized across different directories. • jboss/client - this folder contains all the jar files used by any client application for jboss. , for example a swing application that needs to commnicarte with a remote JBoss instance would need to have the jar files in this directory in its classpath or it will not be able to communicate correctly.  • jboss/common/lib – this folder is meant to hold jar files that should be made available to all JBoss instances. Jar files global to all applications go here. • jboss/lib – this folder holds all the jar files used in order for the server to run correctly. • jboss/lib/endorsed – this folder holds all the endorsed libs that jboss uses where other implementations can be used to override. Xalan implementations other than the default go here if you want to override with a newer version.  • jboss/server/<configured instance>/lib – this is where you put any instance specific jar files. • The most easy pitfalls include more than one library being loaded, but of a different version. Which one gets loaded if there is more than one? The answer depends on the strategy you used in your setup, and figuring out the best strategy for your particular application(s) is paramount to minimizing this risk.

21. Deploying third party library files. • One strategy of minimizing the immediate class loading problem while loading the third party jar files is to package all your third party libraries in the right lib directory for your war or ear file to make it a portable and completely self contained application. • Cons: It inflates the server startup time or deployment time. • Second strategy is to put third party application jar file inside (jboss/server/<configured instance>/lib) folder. Comparatively efficient than the strategy 1. • Cons:  Deployable artifact is no longer completely self contained. • Que: What happens if you have more than one library, say one in your war file, and another one in the instance lib, which one gets used by your code? • Ans:It turns out that the order in which the classes are loaded matters and is the determining factor. The server global directory loads before the instance specific lib, and the instance specific lib loads before your deployable artifacts and their libraries. So basically, the more global libraries will outweigh the artifact local libraries.

22. ClassLoading issue : ClassCastException • A java.lang.ClassCastException results whenever an attempt is made to cast an instance to an incompatible type. A simple example is trying to obtain a String from a List into which a URL was placed: • Consider the case of a JAR being loaded by different class loaders. Although the classes loaded through each class loader are identical in terms of the bytecode, they are completely different types as viewed by the Java type system. • Usually occurs when redeploying an application to which other applications are holding references to classes from the redeployed application. For example, a standalone WAR accessing an EJB. If you are redeploying an application, all dependent applications must flush their class references. Typically this requires that the dependent applications themselves be redeployed. • Remedy would be to isolating the dependencies. ArrayList array = new ArrayList(); array.add(new URL("file:/tmp")); String url = (String) array.get(0); java.lang.ClassCastException: java.net.URL at org.jboss.book.jmx.ex0.ExCCEa.main(Ex1CCE.java:16)

23. ClassLoading issue : IllegalAccessExecption • A java.lang.IllegalAccessException is thrown when one attempts to access a method or member that visibility qualifiers do not allow. Typical examples are attempting to access private or protected methods or instance variables. Another common example is accessing package protected methods or members from a class that appears to be in the correct package. • An example of how this can happen in practice is to include the same classes in two different SAR deployments. If classes in the deployment have a package protected relationship, users of the SAR service may end up loading one class from SAR class loading at one point, and then load another class from the second SAR at a later time. If the two classes in question have a protected access relationship an IllegalAccessError will result. The solution is to either include the classes in a separate jar that is referenced by the SARs, or to combine the SARs into a single deployment. This can either be a single SAR, or an EAR that includes both SARs.

24. ClassNotFoundException • A class not found exception results when the following conditions exist and can be corrected by the following actions: • The class is not visible on the logical classpath of the context class loader. • The class not found is not in the logical class path of the class loader associated with the current thread. The logical classpath is the accumulation of all classpaths searched when a load operation is invoked on a class loader.  • Remedy: If the JAR file is not in the list, the class likely is not in the logical class path, not readable or an alternate class is already loaded. Move the class to a location that enables it to be loaded. • The application incorrectly uses a class loader API. • The application may be incorrectly using the class loader application programming interface (API). For example, the class name is incorrect, the class is not visible on the logical classpath of that class loader, or the wrong class loader was engaged. • Remedy: Determine whether the class exists and whether the application is properly using the class loader API • A dependent class is not visible. • Occurs when the dependency classes are not visible. • Remedy: Make sure that all the dependent jars / classes are loaded.

25. Scoping Classes. • Process of making the libraries used by your deployment localized, superseding the global libraries with what’s packaged in the artifact. • If you want to deploy multiple versions of an application you need to use Deployment Based Scoping. With deployment based scoping, each deployment creates its own class loader repository with the help of UnifiedLoaderRepository. • LoaderRepository:- This is an MBean that contains operations to display class and package information. The default repository is located under a standard JMX name of JMImplementation:name=Default,service=LoaderRepository

26. Scoping Classes The deployment scope class is very specific to the JBoss Application Server and hence the entry goes into the Jboss Specific Deployment Descriptor. For Ear files you will need to add an entry to your jboss-app.xml: For War files you will need to add an entry to your jboss-web.xml file: <jboss-app>     <loader-repository>   com.example:archive=name-of-your-deployable-artifact.ear        <loader-repository-config>        java2ParentDelegation=false        </loader-repository-config>     </loader-repository>   </jboss-app>   <jboss-web>      <class-loading java2ClassLoadingCompliance="false">         <loader-repository>  com.example:archive=name-of-your-deployable-artifact.war            <loader-repository-config>               java2ParentDelegation=false            </loader-repository-config>         </loader-repository>      </class-loading>   </jboss-web>  

27. Debugging Class Loading issues • Debugging class loading issues comes down to finding out where a class was loaded from. • JBoss provides an utility class “org.jboss.util.Debug” to get a detailed information about the classes loaded and the classloader. • Beyond that it may be useful to view the details of classes being loaded into the JBoss server. You can enable verbose logging of the JBoss class loading layer using a Log4j configuration fragment. • Note: This configuration snippet would generate a log file containing the trace for the classes loaded and can be used for trouble shooting. • <appender name="UCL" class="org.apache.log4j.FileAppender"> • <param name="File" value="${jboss.server.home.dir}/log/ucl.log"/> • <param name="Append" value="false"/> • <layout class="org.apache.log4j.PatternLayout"> • <param name="ConversionPattern" value="[%r,%c{1},%t] %m%n"/> • </layout> • </appender> • <category name="org.jboss.mx.loading" additivity="false"> • <priority value="TRACE" class="org.jboss.logging.XLevel"/> • <appender-ref ref="UCL"/> • </category>

28. Specifying Isolation • For .ear files, in your jboss-app.xml, add the following descriptor fragment construct to enable scoped class loading: <jboss-app> <loader-repository>com.example:archive=unique-archive-name    </loader-repository> </jboss-app>  • For .war files, in your jboss-web.xml, the following template applies: <jboss-web>    <class-loading>       <loader-repository>com.example:archive=unique-archive-name</loader-repository>    </class-loading> </jboss-web>