Thursday, January 29, 2015

WLST: Understanding WebLogic Server MBean Tree


The JMX specification does not impose a model for organizing MBeans. However, because the configuration of a WebLogic Server domain is specified in an XML document, WebLogic Server organizes its MBeans into a hierarchical model that reflects the XML document structure.[1]

With WLST, you can navigate the hierarchy in a filesystem-like structure with subdirectories representing parent-child relationships. There are also "soft-links" with the ability to use the cd command to jump to other positions in the tree (very similar to what can be done on UNIX using the ln -s command).

In this article, we will cover different MBeen trees implemented in the WebLogic Server 12c.

Configuration vs. Runtime


There are two main kinds of MBeans in WLS:
  • Configuration
    • Used to configure WLS
    • To navigate to a configuration MBean from the runtime hierarchy, enter the serverConfig or domainConfig () command.
    • To edit configuration beans, you must be connected to an Administration Server, and you must navigate to the edit tree (see below) and start an edit session, as described in edit and startEdit, respectively.[7]
  • Runtime
    • Used to monitor WLS and for some operation control—starting and stopping servers, shrinking data source connection pools.
    • The root of the runtime MBeans is ServerRuntimeMBean
    • When connected to 
      • Administration Server
        • You access the runtime MBean hierarchy by entering the serverRuntime() or the domainRuntime() command
      • Managed Server
        • You access the runtime MBean hierarchy by entering the serverRuntime() command

MBean Tree


WLS provides the following bean trees:
  • edit
    • Only available on the admin server, used to modify the configurationconfig.xml and system resource files.
    • In the configuration hierarchy, the root directory is DomainMBean; the MBean type is a subdirectory under the root directory; each instance of the MBean type is a subdirectory under the MBean type directory; and MBean attributes and operations are nodes (like files) under the MBean instance directory. 
  • runtime
    • Available on every server, used to view the configuration that server is using, and to access its monitoring data
  • domain runtime
    • Only available on the admin server, shadows the runtime beans of all of the running servers, provides single point of access for monitoring

Tree Commands


WLST provides simplified access to MBeans. While JMX APIs require you to use JMX object names to interrogate MBeans, WLST enables you to navigate a hierarchy of MBeans in a similar fashion to navigating a hierarchy of files in a file system.  Tree commands in WLST can be used to access to all the bean trees within a domain, 
  • edit
    • You can update an existing WebLogic domain in two modes:[6]
      • Offline mode[3]
      • Online mode[4]
    • When you connect to admin server, WLST first connects to a WebLogic Server instance at the root of the server's configuration MBeans, a single hierarchy whose root is DomainMBean. WLST commands provide access to all the WebLogic Server MBean hierarchies within a WebLogic domain, such as a server's run-time MBeans, run-time MBeans for domain-wide services, and an editable copy of all the configuration MBeans in the domain. For more information, see "Tree Commands"[8]
  • runtime
    • When connected to either an admin server or a managed server, you can access the run-time MBean hierarchy by entering the serverRuntime() command
      • The serverRuntime() command places WLST at the root of the server run-time management objects, ServerRuntimeMBean.
  • domain runtime
    • When connected to an admin server,  you can access the domain run-time MBean hierarchy by entering domainRuntime() command.
      • The domainRuntime() command places WLST at the root of the domain-wide run-time management objects, DomainRuntimeMBean.

References

  1. WebLogic Server MBean Data Model
  2. Navigating and Interrogating MBeans
  3. Using WLST Offline to Update an Existing WebLogic Domain
  4. Using WLST Online to Update an Existing WebLogic Domain
  5. Editing Commands Reference
  6. WLST: Offline and Online Modes (Xml and More)
  7. Configuration MBean Hierarchy
  8. WebLogic Scripting Tool Command Reference
  9. Oracle WebLogic Server on Docker Containers (white paper)
  10. WebLogic on Docker (GitHub)
    • Sample Docker configurations to facilitate installation, configuration, and environment setup for DevOps users. This project includes quick start dockerfiles and samples for both WebLogic 12.1.3 and 12.2.1 based on Oracle Linux and Oracle JDK 8 (Server).

Sunday, January 25, 2015

Java Evolution: JDK and JRE File Structure

"JDK and JRE File Structure" describes the most important files and directories required to develop applications for the Java platform. In [1], it states that there will be new changes in coming Java 9 such as:
  • JRE and JDK images now have identical structures.
    • Previously a JDK image embedded the JRE in a jre subdirectory; now a JDK image is simply a run-time image that happens to contain the full set of development tools and other items historically found in the JDK.
  • The internal files rt.jar, tools.jar, and dt.jar have been removed.
  • The extension mechanism has been removed.
  • The endorsed-standards override mechanism has been removed.

In this article, we will take one step back to see how "JDK and JRE File Structure" has evolved from Java 6 to 8. Note that the file structure of the JRE is identical to that of the JDK's jre directory.

Java 6


Assuming the JDK software is installed at /jdk1.6.0, here are some of the most important directories:[2]


               jdk1.6.0
        ___________|____________________ ________________________
       |           |                    |                        |
      bin         lib                  jre                     include     
       |           |          __________|_____________________
   java.exe    tools.jar     |                                |        
   javac.exe   dt.jar       bin                              lib                
   javap.exe            _____|____ __________         ________|_______ ________ ________        
   javah.exe           |          |          |       |        |       |        |        |
   javadoc.exe     java.exe    client      server  rt.jar    ext  security  applet    fonts
                   java.dll       |          |   charsets.jar |                  
                   awt.dll     jvm.dll    jvm.dll        localedata.jar      

Java 7


As part of the Java 7 release, the Java Development Kit (JDK) now includes the SDK for developing JavaFX applications and, more importantly, the JavaFX Runtime is now installed with the JRE.[3] In addition, there is new db sub-folder under the root directory of JDK software installation.

Assuming the JDK software is installed at /jdk1.7.0, here are some of the most important directories:[4]


               jdk1.7.0
        ___________|____________________ __________________________ _______
       |           |                    |                          |       |

      bin         lib                  jre                      include    db
       |           |          __________|________________________
   java.exe  ant-javafx.jar  |                                   |        
   javac.exe   dt.jar       bin                                 lib                
   javap.exe tools.jar  _____|____ __________          __________|_______ ________ ________        
   javah.exe           |          |          |        |          |       |        |        |
   javadoc.exe     java.exe    client      server   rt.jar      ext  security  applet    fonts
                   java.dll       |          |    charsets.jar   |                  
                   awt.dll     jvm.dll    jvm.dll   jfxrt.jar  localedata.jar      

Java 8


In Java 8, jfxrt.jar has become one of the optional packages (what used to be known as standard extensions).[6] So, it has been moved into /lib/ext.

Assuming the JDK software is installed at /jdk1.8.0, here are some of the most important directories:


               jdk1.8.0
        ___________|____________________ __________________________ _______
       |           |                    |                          |       |

      bin         lib                  jre                      include    db
       |           |          __________|________________________
   java.exe  ant-javafx.jar  |                                   |        
   javac.exe   dt.jar       bin                                 lib                
   javap.exe tools.jar  _____|____ __________          __________|_______ ________ ________        
   javah.exe           |          |          |        |          |       |        |        |
   javadoc.exe     java.exe    client      server   rt.jar      ext  security  applet    fonts
                   java.dll       |          |    charsets.jar   |                  
                   awt.dll     jvm.dll    jvm.dll              localedata.jar    
                                                               jfxrt.jar

Directory Summary


Directory
Contains
Setup
<jdk1.x.0>/bin
Executables for all the development tools contained in the JDK.
The PATH environment variable should contain an entry for this directory.
<jdk1.x.0>/lib Files used by the development tools.
<jdk1.x.0>/jre Root directory of the Java Runtime Environment (JRE) used by the JDK development tools. This is the directory referred to by the java.home system property.
<jdk1.x.0>/jre/bin Executable files for tools and libraries used by the Java platform.
The executable files are identical to files in /jdk1.x.0/bin.

This directory does not need to be in the PATH environment variable.
<jdk1.x.0>/jre/lib Code libraries, property settings, and resource files used by the JRE.
<jdk1.x.0>/jre/lib/ext Default installation directory for extensions to the Java platform.
See The Extension Mechanism
<jdk1.x.0>/jre/lib/security Contains files used for security management. These include the security policy java.policy and security properties java.security files.
<jdk1.x.0>/jre/lib/amd64 Contains the .so (shared object) files used by the architecture amd64 release of the Java platform

<jdk1.x.0>/jre/lib/amd64/server Contains the .so file used by the Java HotSpot VM server.
<jdk1.x.0>/jre/lib/applet JAR files that contain support classes for applets can be placed in the lib/applet/ directory.
This reduces startup time for large applets by allowing applet classes to be preloaded from the local file system by the applet class loader and provides the same protections as though they had been downloaded over the Internet.

<jdk1.x.0>/jre/lib/fonts Font files used by the platform.


References

  1. Project Jigsaw: Modular run-time images
  2. JDK and JRE File Structure (Java 6, Linux version)
  3. Java 7 Now Includes JavaFX
  4. JDK and JRE File Structure (Java 7, Linux version)
  5. JDK and JRE File Structure (Java 8, Linux version)
  6. Extension Mechanism Architecture
  7. WebLogic's Classloading Framework (Xml and More)
  8. java.lang.UnsatisfiedLinkError: Setting Environment Variable (Xml and More)
  9. Compatibility Guide for JDK 8

Tuesday, January 20, 2015

JAXP 1.6: Use of the Service Provider Loader Facility Is Required

In this article, we will first cover the pluggability layer supported in JAXP 1.5 (bundled with Java SE 7).[1] Then discuss new requirements in JAXP 1.6 (bundled with Java SE 8) for service providers.[2] Finally, we will touch upon Jigsaw project to understand JCP's decision to undertake such changes in JAXP 1.6, which aims to smooth the eventual transition to modules in Java 9.

Pluggability Layer


Designed to be flexible, JAXP allows you to use any XML-compliant processors from within your application. It does this with the factory APIs provided in jaxp-api.jar. High-level factory APIs will remain stable and are not subject to change. This jar contains:
  • javax.xml.datatype
  • javax.xml.namespace
  • javax.xml.parsers
  • javax.xml.stream
  • javax.xml.transform
  • javax.xml.validation
  • javax.xml.xpath
packages.

These packages contain the factory APIs that give applications a consistent way to obtain instances of XML processing implementations. Each factory class is an abstract class that has a static newInstance() method that enables you to obtain a concrete instance of the abstract factory class. This static method uses an ordered lookup procedure to determine which concrete implementation of the abstract factory class to load.

This procedure applies to all factory classes. For example, xmlparserv2.jar in Oracle XDK for Java has the following factory types supported:[4]
  • SAXParserFactory
  • DocumentBuilderFactory
  • TransformerFactory
Using SAXParserFactory as an example, the service provider mechanism works in JAXP 1.5 as follows:[7]
  1. Use system property
    • E.g. -Djavax.xml.parsers.SAXParserFactory=.
  2. Use the properties file "lib/jaxp.properties" in the JRE directory
    • This configuration file is in standard java.util.Properties format and contains the fully qualified name of the implementation class with the key being the system property defined above.
    • The jaxp.properties file is read only once by the JAXP implementation and it's values are then cached for future use. If the file does not exist when the first attempt is made to read from it, no further attempts are made to check for its existence. It is not possible to change the value of any property in jaxp.properties after it has been read for the first time.
  3. Use the Services API (as detailed in the JAR specification)
    • The Services API will look for a classname in the file META-INF/services/javax.xml.parsers.SAXParserFactory in jars available to the runtime.
  4. Use Platform default SAXParserFactory instance.
Once an application has obtained a reference to a SAXParserFactory it can use the factory to configure and obtain parser instances.

Transition to Modularization


As described in [3], the project Jigsaw[9] was postponed to Java 9. This project is to design and implement a standard module system for the Java SE Platform and to apply that system to the Platform itself, and to the JDK.

To smooth the transition to Java 9, JAXP 1.6 bundled in Java SE 8 has adopted JEP 162[5] recommended changes—one of which requires the use of the service provider loader facility defined by java.util.ServiceLoader[6] to load services from service configuration files.
  • The rationale for this is to allow for future modularization of the Java SE platform where service providers may be deployed by means other than JAR files and perhaps without the service configuration files.
  • Note that the JAXP has always specified the use of the 'Services API' without reference to a specific API or service provider loading facility.
There are several APIs in the JDK that have their own service provider mechanism rather than using java.util.ServiceLoader. The various FactoryFinders in pre-1.6 JAXP's are examples. These provider loading mechanisms are problematic for modules because they are non-standard. Therefore, JEP 162[5] has proposed to change these APIs to use java.util.ServiceLoader. So, the description of step 3 in the previous-stated "service provider mechanism" should be changed in JAXP 1.6 to:
3, Use the service-provider loading facilities

JAXP: How to Retrieve Its Specification and Implementation Versions

In [1], we have discussed Package objects in Java are used to track a package's version information.  In this article, we will use JAXP 1.3 to demonstrate how version information is stored and retrieved.

JAXP


The Java API for XML Processing (JAXP) enables applications to parse, transform, validate and query XML documents using an API that is independent of a particular XML processor implementation. JAXP provides a pluggability layer to enable vendors to provide their own implementations without introducing dependencies in application code. Using this software, application and tool developers can build fully-functional XML-enabled Java applications for e-commerce, application integration, and web publishing.

The latest JAXP released with Java SE 8 is JAXP 1.6.[2]  It provides the capability of validating and parsing XML documents. The three basic parsing interfaces are:
In addition to the parsing interfaces, the API provides an XSLT interface to provide data and structural transformations on an XML document.

Instead of using the lastest JAXP 1.6, we have chosen an older version 1.3 for demonstration.  But, the principles remain the same (see [2] for JAXP 1.6 changes).

Specification and Implementation Version Information


In JAXP 1.3, specification version information is made available via the following java.lang.Package methods:
  • public String getSpecificationTitle()
    • Returns the title of the specification that this package implements. null is returned if it is not known.
  • public String getSpecificationVersion()
    • Returns the version number of the specification that this package implements. This version string must be a sequence of positive decimal integers separated by "."'s and may have leading zeros. 
    • When version strings are compared the most significant numbers are compared. null is returned if it is not known.
  • public String getSpecificationVendor()
    • Returns the name of the organization, vendor, or company that owns and maintains the specification of the classes that implement this package. null is returned if it is not known.
This version information is retrieved and made available by the ClassLoader instance that loaded the class(es). For example, a typical implementation will provide this information with the following values:
  • Specification-Title : Java API for XML Processing
  • Specification-Vendor : Sun Microsystems, Inc.
  • Specification-Version : 1.3
in the manifest (i.e., META-INF/MANIFEST.MF).

Implementation version information is also made available via the following java.lang.Package methods:
  • public String getImplementationTitle()
    • Returns the title of this implementation. null is returned if it is not known.
  • public String getImplementationVersion()
    • Returns the version of this implementation. It consists of any string assigned by the vendor of this implementation and does not have any particular syntax specified or expected by the Java runtime. 
    • It may be compared for equality with other package version strings used for this implementation by this vendor for this package. null is returned if it is not known.
  • public String getImplementationVendor()
    • Returns the name of the organization, vendor or company that provided this implementation.
This version information is retrieved and made available by the ClassLoader instance that loaded the class(es). For example, a typical implementation will provide this information with the following values:
Implementation-Title : Oracle XML Developer's Kit
Implementation-Vendor : Oracle USA, Inc.
Implementation-Version : 11.1.0.0.0

in the manifest (i.e., META-INF/MANIFEST.MF).

References

  1. Java Package: How to Retrieve Its Version Information
  2. JAXP 1.6 Enhancements in Java SE 8
    • JAXP 1.6 requires the use of the service provider loader facility defined by java.util.ServiceLoader to load services from service configuration files
      • The rationale for this is to allow for future modularization of the Java SE platform where service providers may be deployed by means other than JAR files and perhaps without the service configuration files. 
      • Note that the JAXP has always specified the use of the 'Services API' without reference to a specific API or service provider loading facility.
    • For more information see JEP 162: Prepare for Modularization as well as the JAXP 1.6 Change List.
  3. Project JAXP (Glassfish)



Thursday, January 8, 2015

Java Package: How to Retrieve Its Version Information

Packages define the consistent Java unit that can be developed, packaged, verified, updated, and distributed. Per package manifest information identifies the contents of the package.  When bugs occur, users need to report the following information to aid the debugging process:
  1. What version of the Java Runtime is active?
  2. What version of the Java VM is active?
  3. What are the packages loaded?
  4. What are the package versions?
You can read [1] to answer questions 1 and 2.  In this article, we will tackle issues 3 and 4.

java.lang.Package Object


Package object contain version information—typically, it is stored in the manifest—about the implementation and specification of a Java package. This version information is retrieved and made available by the ClassLoader instance that loaded the class(es). Within each ClassLoader instance, all classes from the same java package have the same Package object.

For demonstration,we have used the following code snippets to retrieve package's version information:


public class GetPackageVersion {

   public static void main(String[] args) {

      // get all the packages
      Package[] pack = Package.getPackages();

      // print all packages, one by one
      for (int i = 0; i < pack.length; i++) {
         System.out.println("" + pack[i].getName());
         System.out.println("  Specification: " + pack[i].getSpecificationVendor() + "," +
                pack[i].getSpecificationTitle() + "," + pack[i].getSpecificationVersion());
         System.out.println("  Implementation: " + pack[i].getImplementationVendor() + "," 
                + pack[i].getImplementationTitle() + "," + pack[i].getImplementationVersion());
      }
   }
}

The Package.getPackages() method gets all the packages currently known for the caller's ClassLoader instance. If the caller's ClassLoader instance is the bootstrap ClassLoader instance,[4] only packages corresponding to classes loaded by the bootstrap ClassLoader instance will be returned.  For example, this is what returned by our bootstrap ClassLoader instance:

sun.reflect
  Specification: Oracle Corporation,Java Platform API Specification,1.8
  Implementation: Oracle Corporation,Java Runtime Environment,1.8.0_40-internal
java.util
  Specification: Oracle Corporation,Java Platform API Specification,1.8
  Implementation: Oracle Corporation,Java Runtime Environment,1.8.0_40-internal
...

MANIFEST.MF


Java products are distributed by putting packages into archive files. Archives include a manifest to identify the product version and packages it contains.  For example, this is the MANIFEST.MF file of rt.jar:

$ cat MANIFEST.MF
...
Implementation-Vendor: Oracle Corporation
Implementation-Title: Java Runtime Environment
Implementation-Version: 1.8.0_40-internal
...
Specification-Vendor: Oracle Corporation
Specification-Title: Java Platform API Specification
Specification-Version: 1.8
...

The output of Package objects from the previous section actually return the version information contained in the manifest file as shown above.

References

  1. Java Products: All About Versions (Xml and More)
  2. Java™ Product Versioning (Java SE 7)
  3. java.lang.Package
  4. WebLogic's Classloading Framework (Xml and More)
  5. Module Versioning Requirements in Jigsaw Project
  6. java.lang.SecurityManager::checkPackageAccess
  7. JAXP: How to Retrieve Its Specification and Implementation Versions (Xml and More)

Wednesday, January 7, 2015

Java Products: All About Versions

When Java based products evolves, correct operation depends on the knowledge of:
  • What product version to ask for to get particular features
  • What bugs are in what product version 

In this article, we will cover all things about versions in Java products (see also [4-8]).

System.getProperties


There are at least two artifacts that need to be identified for Java product versions:
and each needs to be identified at two levels:
  • Specification
  • Implementation

When the Java application starts, the system properties are initialized with information about the run-time environment, which can be retrieved using java.lang.System.getProperties.  For demonstration, we will use the following code snippets to get system properties:

import java.util.*;

public class PrintJavaSystemProps  {
  public static void main(String [ ] args) {
    Properties p = System.getProperties();
    Enumeration keys = p.keys();
    while (keys.hasMoreElements()) {
      String key = (String)keys.nextElement();
      String value = (String)p.get(key);
      System.out.println(key + ": " + value);
    }
  }
}

To complete, here are the command lines we used to compile and execute the code:

$cat printSysProps.sh

#!/bin/bash
export JAVA_HOME=~/JVMs/jdk-hs
$JAVA_HOME/bin/javac -d . -cp $JAVA_HOME/jre/lib PrintJavaSystemProps.java
$JAVA_HOME/bin/java -cp . PrintJavaSystemProps >systemProperties.txt

General Version Information


From the output of System.getProperties() method, here are the list of relevant version information of Java products:
  • java.version: 1.8.0_40-internal
    • Is displayed on the first line of the output of the java -version command (see example below) in the following format:
    • major_version.minor_version.micro_version[_update_version][-milestone]
  • java.runtime.version: 1.8.0_40-internal-20141227004606.gziemski.jdk8_after-b00
    • Identifies the Java SE JDK/JRE version and build
    • Is displayed on the second line of the output of the java -version command in the following format:
      • major_version.minor_version.micro_version[_update_version][-milestone]-build
  • java.vm.version: 25.40-b23
    • Identifies the JVM implementation version
    • Is displayed on the third line of the output of the java -version command.
  • java.class.version: 52.0
    • Displays the major and minor versions of the class file (see example below)
  • java.specification.version: 1.8
    • Identify the version of the Java Runtime Environment specification that this implementation adhere’s to
  • java.vm.specification.version: 1.8
    • Identifies the version of the JVM specification on which the HotSpot JVM instance is based
The output of the java -version command:

$~/JVMs/jdk-hs/bin/java -version
java version "1.8.0_40-internal"
Java(TM) SE Runtime Environment (build 1.8.0_40-internal-20141227004606.gziemski.jdk8_after-b00)
Java HotSpot(TM) 64-Bit Server VM (build 25.40-b23, mixed mode)


The output of javap (i.e., class file disassembler) command:

 ~/JVMs/jdk-hs/bin/javap -verbose ./PrintJavaSystemProps.class |grep 'major\|minor'
  minor version: 0
  major version: 52


Version Identification of the Java Virtual Machine


An implementation of the Java Virtual Machine should be identify both the specification and the implementation as shown below:

java.vm.specification.version: 1.8
java.vm.specification.vendor: Oracle Corporation
java.vm.specification.name: Java Virtual Machine Specification

java.vm.version: 25.40-b23
java.vm.vendor: Oracle Corporation
java.vm.name: Java HotSpot(TM) 64-Bit Server VM


Version Identification of the Java Runtime Environment


An implementation of the Java Runtime  should be identify both the specification and the implementation as shown below:

java.specification.version: 1.8
java.specification.name: Java Platform API Specification
java.specification.vendor: Oracle Corporation

java.version: 1.8.0_40-internal
java.vendor: Oracle Corporation

References

  1. Java™ Product Versioning
  2. Oracle JRockit JVM System Properties
  3. Java Runtime Environment (JRE)
    • The Java Runtime Environment (JRE), also known as Java Runtime, is part of the Java Development Kit (JDK), a set of programming tools for developing Java applications.
    • The Java Runtime Environment provides the minimum requirements for executing a Java application; it consists of the Java Virtual Machine (JVM), core classes, and supporting files.
  4. How to find Oracle WebLogic Server Version? (Xml and More)
  5. How to Determine JDBC Driver Version Installed with WebLogic Server? (Xml and More)
  6. Oracle Products: What Patching, Migration, and Upgrade Mean? (Xml and More)
  7. java.lang.ClassCastException: [I cannot be cast to java.util.List. (Xml and More)
    • The compiler is not backwards compatible because bytecode generated with JDK 7 won't run in Java 1.6 VM (unless compiled with the -target 1.6 flag). But the JVM is backwards compatible, as it can run older bytecodes.
  8. Module Versioning Requirements in Jigsaw Project
    • Upgradeable modules — If a JDK module implements an endorsed standard or standalone technology then it must be possible to use a version of that module from a later release in any phase, i.e., at compile time, build time, or run time.
  9. JAXP: How to Retrieve Its Specification and Implementation Versions (Xml and More)
  10. Java Package: How to Retrieve Its Version Information (Xml and More)