Child pages
  • MidStream
Skip to end of metadata
Go to start of metadata

Overview

MidStream is a tool for rapidly building consistent, high-quality, lightweight service-oriented middle-ware applications. MidStream is based on the Spring framework and utilizes several open source solutions for value-added integration. The MidStream tools suite consists of two parts: a lightweight framework library and an IDE plug-in for IntelliJ.

While there are a myriad of development tools and plug-ins that can be individually leveraged to construct SOA applications, MidStream attempts to consolidate/integrate several best-of-breed tools/frameworks into a single platform for end-to-end development of service-oriented middle-ware.

MidStream eliminates the need to manually code boilerplate for common development tasks. The MidStream framework library automatically performs performance and event logging around all component invocations and setting of timeouts for outbound communication components. The plug-in adds the following core wizards/views to IntelliJ:

  • Wizards for creating MidStream projects
  • Wizards for creating a variety of client/service components
  • A wizard for managing the project's dependencies/libraries
  • A view for monitoring the deployed application's performance logging
  • A view for viewing/managing the application's (Spring) context definitions
  • A view for creating/running functional tests against the deployed project

MidStream provides wizards and wrappers for creating three different types of service components:

  1. Remoting
    • Java/HTTP - Utilizes Spring's HTTP exporters to expose a POJO as a distributed service using simple Java serialization over HTTP
    • Custom XML/HTTP - Utilizes Spring's Web MVC and JiBX to expose a POJO as a service endpoint accepting simple XML via an HTTP POST
    • XML-RPC - Utilizes Spring's Web MVC and Apache's XML-RPC library to expose a POJO as an XML-RPC specification compliant service endpoint.
    • SOAP - Utilizes XFire to expose a POJO as a SOAP-style Web Service
  2. Messaging - Utilizes Spring's asynchronous message receiving support classes for creating POJO messaging receivers for both JMS queues and topics.
  3. Scheduling - Utilizes Spring's timer based support classes for invoking a service endpoint on a repeating schedule similar to 'cron'.

MidStream provides wizards and wrappers for creating eight types of client/connector components:

  1. Configuration - Utilizes Commons Configuration to encapsulate application data in XML format that can hot deployed and reloaded
  2. Caching - Utilizes Ehcache to provide a caching mechanism for application components
  3. Data Access Objects - Utilizes Spring JDBC and the DAO pattern to encapsulate accessing a DBMS.
  4. XML-RPC Client - Utilizes Apache's XML-RPC library to create a client POJO for a remote XML-RPC service
  5. Socket Client - Creates a client POJO for making general secure/non-secure socket communication calls
  6. HTTP Client - Utilizes Commons HttpClient to create a client POJO for making HTTP GET/POST requests
  7. JMS Message Production - Utilizes Spring's JMS template support classes to create a POJO for producing JMS queue/topic messages
  8. SOAP Web Service Client - Utilizes Apache Axis to create POJO clients for interacting with SOAP exposed Web Services

Installation

MidStream can be installed via IntelliJ by selecting the MidStream plug-in from 'File -> Settings -> Plugins -> Available'. If the plug-in is not listed in the available list, then unzip the accompanying 'MidStream.zip' file into your IntelliJ's plug-in directory (e.g. 'C:\opt\IntelliJ IDEA 5.0\plugins').

Note: MidStream was coded against the 5.x version of the Open API and some features are not currently operable in the 6.x version of the IDE. Among these are:

  • Usage of the 'MDS Test Runner'
  • Adding bean properties within the 'Context View'
  • Creating bean definitions from a preexisting POJO

All other functionality appears to have remained usable.

Project Creation

MidStream begins by creating a basic project with the minimum set of configuration and dependencies necessary to build/deploy an SOA application.

Note: MidStream requires connectivity to the Internet (or intranet) for creating new projects and MidStream components. If you develop behind a proxy, create a '%HOME_DIR%/.m2/settings.xml' file (e.g. 'C:\Documents and Settings\user\.m2\settings.xml') with the following contents per your proxy host:

To create a new project:

  1. Select 'File -> New MidStream Project...'
  2. Enter a name for the project (e.g. 'MyProject')
  3. Enter a location for the project (e.g. 'c:\temp'). Note that you can use the browse button ('...') to select a location.
  4. Enter a different deployment prefix if you don't like the default one. This prefix will be used to distinguish project artifacts such as the .war name, log files, URLs, etc.
  5. Enter a different deployment version if you don't like the default of '1.0'. This version will be used in project artifacts such as the .war name, log files, URLs, etc.
  6. Select a JDK for the project. While all currently configured JDKs should show up in the dropdown box for your selection, you can add additional ones by clicking the 'Add' button.
  7. Click the 'OK' button to create the project.
  8. Open the 'Ant View' and click the '+' button to add the project's build file
  9. Click 'Ctrl + 2' to expand the tree view to the project's directory
  10. Select the 'build.xml' under the project's directory and click the 'OK' button
  11. Right click on the project's named node in the 'Ant View' and select 'Properties -> Additional Classpath -> Add'
  12. Click 'Ctrl + 2', expand the 'lib' directory under the project, select the JUnit library, and click 'OK'.
  13. Click 'OK' to close the 'Build File Properties' window

Once this process is complete a new IntelliJ project with a single module will have been created and opened. The project structure is defined as:

Directory/File

Description

conf

Directory containing the project's configuration artifacts. By default the, the following are created initially: deployment descriptors (context.xml, web.xml), logging configuration (log4j.xml), application (Spring) context definitions (applicationContext.xml)

dist

Directory containing the project's distributable artifacts (i.e. the application's .war file, javadocs, etc.)

lib

Directory containing the project's dependencies (i.e. .jar files utilized by IntelliJ and Ant)

mds

Directory where the project's integration/functional tests are stored

src

Directory containing the project's Java source files

test

Directory containing the project's unit test files, reports and coverage data

build.properties

Properties file containing the project's unique data such as name, deployment prefix/version, etc.

build.xml

Ant build file

IntelliJ files (.ipr, .iml, .iws)

Usual IntelliJ project files

pom.xml

Maven2 project file for specifying the project's dependencies (used via the Maven Ant task)

The standard Ant build targets are:

Target

Description

clean

Deletes the temporary build and distribution directories

compile

Compiles the applications source and unit test code

coverage

Generates a unit test code coverage report (via Cobertura)

deploy

Builds and copies the application's .war to locally configured application server (normally Tomcat as defined via the 'CATALINA_HOME' environment variable)

dist

Builds the application's distributable artifacts

init

Creates the temporary build/distribution directories and updates the local project dependencies

javadoc

Generates the project's JavaDocs

test

Runs the project's unit tests

validate-configs

Validates the project's XML files located in the 'conf' directory

Dependency Management

MidStream utilizes a Maven 2 (style) repository for retrieving project libraries. Developers are free to change the location of the repository by modifying the 'remote.repository' property in the project's 'build.properties' file.

Note: Developers can manually add libraries to the project's 'lib' directory; this is ill-advised since the project will most likely be placed in a version control system (that would only be bloated by adding reproducible .jar files better served from a simpler centralized repository).

While MidStream will automatically incorporate the dependencies/libraries needed for creating project components, it may often times be necessary to add additional libraries, update existing libraries and remove old ones. To facilitate these actions, utilize the 'Project Dependencies' wizard via:

  1. Right click on the (top level node) project in the 'Project View'
  2. Select 'Project Dependencies...' menu item

Adding New Libraries

  1. Via the first tab, 'Add Library', in the 'Manage Project Dependencies' wizard, navigate to the dependency of interest and expand all sub-nodes until the versions are displayed.
  2. Check the version that you wish to utilize
  3. Repeat 1 & 2 for all libraries that you wish to add
  4. Check the 'Add to Build Path' box if you wish for the library to be placed on the project's classpath for IntelliJ
  5. Check the 'Add to Deployment Unit' box if you wish for the library to be packaged in the project's .war file under 'WEB-INF/lib'.
  6. Click the 'OK' button to add the dependencies.

Updating Existing Libraries

MidStream can upgrade existing libraries to their latest versions as found in the configured repository. Note that if the libraries are on the build path or are in the deployment unit, then the older versions will be replaced with the newer ones.

  1. Via the second tab, 'Update Library', in the 'Manage Project Dependencies' wizard, check the individual dependencies that you wish to upgrade or click the '*' header to select all.
  2. Click the 'OK' button to update the selected dependencies

Removing Existing Libraries

  1. Via the third tab, 'Remove Library', in the 'Manage Project Dependencies' wizard, check the individual dependencies that you wish to remove or click the '*' header to select all.
  2. Check the 'Remove from Build Path' box if you wish for the selected libraries to be removed from the classpath (if they are on it)
  3. Check the 'Remove from Deployment Unit' box if you wish for the selected libraries to no longer be packaged in the project's .war file
  4. Click the 'OK' button to update the selected dependencies

Component Creation

MidStream provides users with the ability to create three different types of services and eight different types of clients/connectors. In all cases, MidStream removes the need to manually code boilerplate structures to accomplish client/service creation.

In addition to handling the creation of application context definitions for each type of component, MidStream enables users to create bean definitions out of existing POJO objects. To create a bean definition for an existing POJO:

  1. Right click on the POJO Java source to create the definition for and select 'Create Bean Definition'
  2. Enter a name for the bean (e.g. HelloBean)
  3. For each property listed in the 'Bean Properties' table click the corresponding '...' button to set a value for it.
    1. Select the tab of the type of property you wish to add, select:
      1. 'Reference' to add a dependency upon another bean.
        1. Select the desired bean from the 'Bean:' dropdown
        2. Enter the fully-qualified type of the desired bean (preferably its interface if available). The auto-complete list box below will display a list of matching classes as you type. Either select a class from the list or manually type the FQN.
      2. 'Value' to add a primitive value property
        1. Enter the desired value
        2. Select the type of the value from the dropdown
      3. 'Collection' to add a collection property
        1. Select the type of the collection (Properties, List, Map, Set)
        2. Fill in the collection's table by entering:
          1. the relative key/value pairs
          2. a reference's name in the value column and checking the corresponding 'Ref' box
    2. Click the 'OK' button to set the property's value
  4. Repeat step three as necessary
  5. Click the 'OK' button to create the bean definition.

Service Components

Java/HTTP

To create new remote Java/HTTP service:

  1. Right click on the (top-level node) project in the 'Project View' and select 'New -> Remote Service'
  2. Enter the Java package name of the new service POJO (e.g. com.foo.bar)
  3. Enter the name of the service (e.g. HelloService)
  4. Select 'Java/HTTP' as the 'Remoting Type'
  5. Click the 'OK' button to create the service

When the wizard has finished the following would have been performed:

  • An interface with the given service name will have been created as 'src/<package name>/<service name>'
  • A POJO implementation of the interface will have been created as 'src/<package name>/<service name>Impl'
  • A JUnit test class for the service POJO will have been created as 'test/src/<package name>/<service name>Test'
  • The application's context definitions will have been updated with an entry for the endpoint
  • A client context file will have been created as 'conf/clientContext.xml' with a client invoker bean definition
  • The project's build file will have been updated to build a client jar file for accessing the service
  • The latest 'servlet-api' .jar file will have been added to the project and classpath (but not to the deployment unit as this is provided by the application server).

Java/HTTP Client Usage

On the client side, the service's client .jar file should be placed on the classpath along with the 'midstream-framework.jar'. Clients will then be able to access the service via:

Custom XML/HTTP

To create a new remote service that accepts/returns XML based on a custom structure:

  1. Right click on the (top-level node) project in the 'Project View' and select 'New -> Remote Service'
  2. Enter the Java package name of the new service POJO (e.g. com.foo.bar)
  3. Enter the name of the service (e.g. HelloService)
  4. Select 'Custom XML/HTTP' as the 'Remoting Type'
  5. Enter the service method name. This is the name of the Java method to be executed on the service POJO when the endpoint is accessed (e.g. execute).
  6. Enter the name of the request object to create. A Java value data type will be created with this name (in the service's package) and passed to the service method (e.g. HelloRequest).
  7. Enter the name of the response object to create. A Java value data type will be created with this name (in the service's package) and will be returned by the service method (e.g. HelloResponse)
  8. Click the 'OK' button to create the service

When the wizard has finished the following would have been performed:

  • An interface with the given service name will have been created as 'src/<package name>/<service name>'
  • A POJO implementation of the interface will have been created as 'src/<package name>/<service name>Impl'
  • A JUnit test class for the service POJO will have been created as 'test/src/<package name>/<service name>Test'
  • The application's context definitions will have been updated with an entry for the endpoint
  • A JiBX bindings file will have been created as 'conf/<service name>.xml' that describes how the XML to request/response objects should be done.
  • The project's build file will have been updated with a target ('run-jibx') to perform the byte-code manipulation on the request/response objects for XML marshalling/un-marshalling.
  • The latest JiBX libraries and dependencies will have been added to the project, classpath and deployment unit

Note: As you modify the request/response objects it will be necessary to update the bindings file to have the modifications reflected at runtime. Running of the 'run-jibx' target will automatically occur when the 'dist' target is run.

XML-RPC

To create new remote XML-RPC service:

  1. Right click on the (top-level node) project in the 'Project View' and select 'New -> Remote Service'
  2. Enter the Java package name of the new service POJO (e.g. com.foo.bar)
  3. Enter the name of the service (e.g. HelloService)
  4. Select 'XML-RPC' as the 'Remoting Type'
  5. Click the 'OK' button to create the service

When the wizard has finished the following would have been performed:

  • An interface with the given service name will have been created as 'src/<package name>/<service name>'
  • A POJO implementation of the interface will have been created as 'src/<package name>/<service name>Impl'
  • A JUnit test class for the service POJO will have been created as 'test/src/<package name>/<service name>Test'
  • The application's context definitions will have been updated with an entry for the endpoint
  • The latest Apache XML-RPC libraries and dependencies will have been added to the project, classpath and deployment unit

SOAP

To create new remote SOAP Web Service:

  1. Right click on the (top-level node) project in the 'Project View' and select 'New -> Remote Service'
  2. Enter the Java package name of the new service POJO (e.g. com.foo.bar)
  3. Enter the name of the service (e.g. HelloService)
  4. Select 'SOAP' as the 'Remoting Type'
  5. Click the 'OK' button to create the service

When the wizard has finished the following would have been performed:

  • An interface with the given service name will have been created as 'src/<package name>/<service name>'
  • A POJO implementation of the interface will have been created as 'src/<package name>/<service name>Impl'
  • A JUnit test class for the service POJO will have been created as 'test/src/<package name>/<service name>Test'
  • The application's context definitions will have been updated with an entry for the endpoint
  • The latest XFire libraries and dependencies will have been added to the project, classpath and deployment unit

Once the application is deployed, XFire will automatically create and expose a WSDL for the service endpoint via 'http://host:port/<deployment prefix>-<deployment version>/remote/Remote<service name>?WSDL' (e.g. 'http://localhost:8080/myservice-1.0/remote/RemoteHelloService?WSDL').

JMS Message Receiver

To create a new JMS message receiver:

  1. Right click on the (top-level node) project in the 'Project View' and select 'New -> JMS Receiver'
  2. Enter the Java package name of the new POJO receiver (e.g. com.foo.bar)
  3. Enter the name of the receiver (e.g. HelloReceiver)
  4. Enter the number of concurrent listeners the application should support. The default is '1'.
  5. Enter the destination's name. This is the name of the queue/topic that the receiver will be consuming (e.g. MyQueue)
  6. Select the destination type (queue or topic).
  7. Enter a user name to be used to connect to the queue/topic if one is required
  8. Enter a password to be used to connect to the queue/topic if one is required
  9. Enter the JNDI name of the connection factory to use. This name will be looked up from the configured JNDI context. (e.g. ConnectionFactory)
  10. Enter the initial naming factory (e.g. org.apache.activemq.jndi.ActiveMQInitialContextFactory)
  11. Enter the provider URL of the queue/topic. (e.g. tcp://hostname:61616)
  12. Enter the security principal (i.e. user name/role) to be used to lookup the destination and connection factory from JNDI
  13. Enter the security credentials (i.e. password/authentication) to be used to lookup the destination and connection factory from JNDI
  14. Click the 'OK' button to create the receiver

When the wizard has finished the following would have been performed:

  • A POJO implementation of the JMS MessageListener, ExceptionListener interfaces will have been created as 'src/<package name>/<receiver name>'
  • A JUnit test class for the receiver POJO will have been created as 'test/src/<package name>/<receiver name>Test'
  • The application's context definitions will have been updated with an entry for the receiver and supporting JNDI beans
  • The JMS 1.1 jar will have been to the project, classpath and deployment unit
  • 'override.properties' files for each environment (Development, Test, Production) will have been created in the 'conf' directory.
  • 'placeholder.properties' files for each environment (Development, Test, Production) will have been created in the 'conf' directory.

Be sure to take note of the reminder to add the necessary message broker libraries to the project. If your vendor's libraries are not available via the repository used by the 'Project Dependencies' wizard, then it will be necessary to manually add related jar files to the project, classpath, and deployment unit. Also remember to update the 'override.properties' and 'placeholder.properties' files per each environment's settings.

Scheduled Service

To create a new scheduled service:

  1. Right click on the (top-level node) project in the 'Project View' and select 'New -> Scheduled Service'
  2. Enter the Java package name of the new POJO scheduled service (e.g. com.foo.bar)
  3. Enter the name of the scheduled service (e.g. HelloSchedule)
  4. Enter the scheduler's delay. This is the number of milliseconds the scheduler should pause prior to running the service. (e.g. '10000' for 10 seconds)
  5. Enter the scheduler's period. This is the frequency at which the scheduler should run the service. (e.g. '60000' for every minute)
  6. Click the 'OK' button to create the scheduled service.

When the wizard has finished the following would have been performed:

  • A simple POJO will have been created as 'src/<package name>/<service name>'
  • A JUnit test class for the POJO will have been created as 'test/src/<package name>/<service name>Test'
  • The application's context definitions will have been updated with an entry for the service and supporting Spring scheduler beans.

Client/Connector Components

Configuration Bean

To create a configuration bean for your application:

  1. Right click on the (top-level node) project in the 'Project View' and select 'New -> Configuration Bean'
  2. Click 'OK' to acknowledge the bean's creation.

When the wizard has finished the following would have been performed:

  • The application's context definitions will have been updated with an entry for the configuration bean.
  • A JUnit test class will have been created as 'test/src/ConfigurationBeanTest'. Feel free to remove this test once the configuration bean is deemed acceptable.
  • 'configuration.xml' files for each environment (Development, Test, Production) will have been created in the 'conf' directory.
  • The latest Commons Configuration libraries and supporting dependencies will have been added to the project, classpath, and deployment unit.

Be sure to place environment specific application data within their respective 'configuration.xml' files prior to deployment.

Cache Manager Bean

To create a cache manager bean for your application:

  1. Right click on the (top-level node) project in the 'Project View' and select 'New -> Cache Bean'
  2. Click 'OK' to acknowledge the bean's creation.

When the wizard has finished the following would have been performed:

  • The application's context definitions will have been updated with an entry for the cache bean.
  • A JUnit test class will have been created as 'test/src/CacheManagerBeanTest'. Feel free to remove this test once the cache manager bean is deemed acceptable.
  • An 'ehcache.xml' file will have been created in the 'conf' directory.
  • The latest Ehcache libraries and supporting dependencies will have been added to the project, classpath, and deployment unit.

Data Access Object

To create a cache manager bean for your application:

  1. Right click on the (top-level node) project in the 'Project View' and select 'New -> Data Access Object (DAO)'
  2. Enter the Java package name of the new POJO DAO (e.g. com.foo.bar)
  3. Enter the name of the DAO (e.g. HelloDAO)
  4. Enter the JNDI name that the desired data source is bound to (e.g. jdbc/TestDS).
  5. Enter the SQL statement (with bind variables as necessary) to be executed by the DAO.
  6. Click the 'OK' button to create the DAO

When the wizard has finished the following would have been performed:

  • An interface with the given DAO name will have been created as 'src/<package name>/<DAO name>'
  • A POJO implementation of the interface will have been created as 'src/<package name>/<DAO name>Impl'
  • A JUnit test class for the DAO POJO will have been created as 'test/src/<package name>/<DAO name>Test'
  • The application's context definitions will have been updated with an entry for the DAO and supporting JNDI beans
  • The application's deployment 'context.xml' will have been updated to add a resource link to the JNDI name for the data source
  • The latest Hypersonic (hsqldb) library will have been added to the project and classpath for unit test purposes.

Note: The generated unit test for the DAO will fail out-of-the-box as it is necessary to manually update it to create the proper tables and data to support the inputted SQL.

XML-RPC Client

To create a new XML-RPC client bean:

  1. Right click on the (top-level node) project in the 'Project View' and select 'New -> XML-RPC Client'
  2. Enter the Java package name of the new POJO client (e.g. com.foo.bar)
  3. Enter the name of the client (e.g. HelloClient)
  4. Enter the name of the XML-RPC method to invoke (e.g. execute).
  5. Enter the connection timeout. This is how long the client will wait to establish a connection with the service. (e.g. 10)
  6. Enter the read timeout. This is how long the client will wait for a response while communicating with the service. (e.g. 10)
  7. Click the 'OK' button to create the client.

When the wizard has finished the following would have been performed:

  • A POJO for the client will have been created as 'src/<package name>/<client name>'
  • A JUnit test class for the client POJO will have been created as 'test/src/<package name>/<client name>Test'
  • The application's context definitions will have been updated with an entry for the client and supporting XML-RPC beans
  • The latest Apache XML-RPC libraries and dependencies will have been added to the project, classpath and deployment unit

Socket Client

To create a new XML-RPC client bean:

  1. Right click on the (top-level node) project in the 'Project View' and select 'New -> Socket Client'
  2. Enter the Java package name of the new POJO client (e.g. com.foo.bar)
  3. Enter the name of the client (e.g. HelloClient)
  4. Check the 'Is Secure?' box if the communication should use SSL.
  5. Enter the host to connect to. This can be a host name or IP (e.g. 127.0.0.1)
  6. Enter the port to connect to (e.g. 80)
  7. Enter the connection timeout. This is how long the client will wait to establish a connection with the service. (e.g. 10)
  8. Enter the read timeout. This is how long the client will wait for a response while communicating with the service. (e.g. 10)
  9. Enter the location of the key store if certificates are necessary.
  10. Enter the type of the key store (e.g. JKS)
  11. Enter the key's algorithm (e.g. DCA)
  12. Enter the name of the secure protocol (e.g. SSLv3)
  13. Click the 'OK' button to create the client.

When the wizard has finished the following would have been performed:

  • A POJO for the client will have been created as 'src/<package name>/<client name>'
  • A JUnit test class for the client POJO will have been created as 'test/src/<package name>/<client name>Test'
  • The application's context definitions will have been updated with an entry for the client

HTTP Client

To create a new HTTP client bean:

  1. Right click on the (top-level node) project in the 'Project View' and select 'New -> HTTP Client'
  2. Enter the Java package name of the new POJO client (e.g. com.foo.bar)
  3. Enter the name of the client (e.g. HelloClient)
  4. Enter the connection timeout. This is how long the client will wait to establish a connection with the service. (e.g. 10)
  5. Enter the read timeout. This is how long the client will wait for a response while communicating with the service. (e.g. 10)
  6. Click the 'OK' button to create the client.

When the wizard has finished the following would have been performed:

  • A POJO for the client will have been created as 'src/<package name>/<client name>'
  • A JUnit test class for the client POJO will have been created as 'test/src/<package name>/<client name>Test'
  • The application's context definitions will have been updated with an entry for the client and supporting HttpClient beans
  • The latest Commons HttpClient libraries and dependencies will have been added to the project, classpath and deployment unit

JMS Message Producer

To create a new JMS message producer:

  1. Right click on the (top-level node) project in the 'Project View' and select 'New -> JMS Message Producer'
  2. Enter the Java package name of the new POJO producer (e.g. com.foo.bar)
  3. Enter the name of the producer (e.g. HelloProducer)
  4. Enter the destination's name. This is the name of the queue/topic that the producer will be publishing to (e.g. MyQueue)
  5. Select the destination type (queue or topic).
  6. Enter a user name to be used to connect to the queue/topic if one is required
  7. Enter a password to be used to connect to the queue/topic if one is required
  8. Enter the JNDI name of the connection factory to use. This name will be looked up from the configured JNDI context. (e.g. ConnectionFactory)
  9. Enter the initial naming factory (e.g. org.apache.activemq.jndi.ActiveMQInitialContextFactory)
  10. Enter the provider URL of the queue/topic. (e.g. tcp://hostname:61616)
  11. Enter the security principal (i.e. user name/role) to be used to lookup the destination and connection factory from JNDI
  12. Enter the security credentials (i.e. password/authentication) to be used to lookup the destination and connection factory from JNDI
  13. Click the 'OK' button to create the producer

When the wizard has finished the following would have been performed:

  • A POJO for the producer will have been created as 'src/<package name>/<producer name>'
  • A JUnit test class for the producer POJO will have been created as 'test/src/<package name>/< producer name>Test'
  • The application's context definitions will have been updated with an entry for the producer and supporting JNDI beans
  • The JMS 1.1 jar will have been to the project, classpath and deployment unit
  • 'override.properties' files for each environment (Development, Test, Production) will have been created in the 'conf' directory.
  • 'placeholder.properties' files for each environment (Development, Test, Production) will have been created in the 'conf' directory.

Be sure to take note of the reminder to add the necessary message broker libraries to the project. If your vendor's libraries are not available via the repository used by the 'Project Dependencies' wizard, then it will be necessary to manually add related jar files to the project, classpath, and deployment unit. Also remember to update the 'override.properties' and 'placeholder.properties' files per each environment's settings.

SOAP Web Service Client

To create a new SOAP Web Service client bean:

  1. Right click on the (top-level node) project in the 'Project View' and select 'New -> SOAP Web Service Client'
  2. Enter the Java package name of the new POJO client (e.g. com.foo.bar)
  3. Enter the name of the client (e.g. HelloClient)
  4. Enter the URL of the service's WSDL (e.g. 'file:/tmp/a.wsdl' or 'http://host/svc/wsdl')
  5. Enter the Java package name for the generated service stubs (from the WSDL)
  6. Enter the read timeout. This is how long the client will wait for a response while communicating with the service. (e.g. 10)
  7. Click the 'OK' button to create the client.

When the wizard has finished the following would have been performed:

  • A POJO for the client will have been created as 'src/<package name>/<client name>'
  • A JUnit test class for the client POJO will have been created as 'test/src/<package name>/<client name>Test'
  • The application's context definitions will have been updated with an entry for the client and supporting Axis beans
  • A 'generate-<client name>-jar' target will have been added (and run) to the project's build file. This target will generate a Java API client jar file for the web service call. The client jar is automatically placed in the project's 'lib' directory and added to the project, classpath, and deployment unit. It is necessary to manually re-run the target whenever the service endpoint's WSDL changes.
  • The latest Apache Axis libraries and dependencies will have been added to the project, classpath and deployment unit

Application Context Management

The 'Context View' can be enabled via 'Window -> Tool Windows -> Context View' and the view should display at the bottom of the IDE. This view provides a graphical view of the application's (Spring) context definitions. The bean representations can be moved around and persisted. The view's toolbar provides the following functions:

  • Refresh - the first toolbar button refreshes the displayed via. It will be necessary to manually refresh the view after most modifications are made to the project's application context.
  • Save - the second toolbar button saves the view's state to 'conf/context_view.xml' so that any manual repositioning of bean representations are not lost.
  • Save As GIF - the third toolbar button enables the user to save the current view as .gif image
  • Zoom - the last toolbar component enables the view to be zoomed in/out

The view also provides (right click) popup menus on the bean representations that enable the user to:

  1. Navigate to the application's context file
  2. Navigate to the bean's implementation class
  3. Add properties to the selected bean. This enables the wiring together of beans in the context view.

To save the view as an image:

  1. Click the third toolbar button (Save As GIF)
  2. Choose the directory to save the image to
  3. Enter the file name of the image
  4. Click the 'Save' button to save the image

To add properties to a bean and/or wire beans together:

  1. Right click on the bean of interest and select 'Source -> Add Property'
  2. Enter the property name to be added to the bean (e.g. newProp)
  3. Check the 'Add Getter/Setter...' box to add getter/setter methods to the bean's Java source file
  4. Select the tab of the type of property you wish to add, select:
    1. 'Reference' to add a dependency upon another bean.
      1. Select the desired bean from the 'Bean:' dropdown
      2. Enter the fully-qualified type of the desired bean (preferably its interface if available). The auto-complete list box below will display a list of matching classes as you type. Either select a class from the list or manually type the FQN.
    2. 'Value' to add a primitive value property
      1. Enter the desired value
      2. Select the type of the value from the dropdown
    3. 'Collection' to add a collection property
      1. Select the type of the collection (Properties, List, Map, Set)
      2. Fill in the collection's table by entering:
      3. the relative key/value pairs
    4. a reference's name in the value column and checking the corresponding 'Ref' box
  5. Click the 'OK' button to create the property

The property will automatically be added to the bean definition in the application's context file and a getter/setter (if chosen) will be created in the bean's Java source file. The context view will automatically refresh to display the new context state.

Application Monitoring

A major part of the MidStream framework is to inject value-add items into the infrastructure on behalf of applications. One such item is the injection of performance and event logging into all entry and exit points to an application. Performance tracking is achieved via the JAMon library by placing monitors around key method invocations. Event logging (via log4j) is also achieved by wrapping key method calls. All of the components in the 'midstream-framework.jar' are enhanced to perform this type of logging. The output from the event logging can only be viewed (by default) in the deployed application's log files. However, the MidStream plug-in provides a view within IntelliJ for monitoring the JAMon output by the deployed application.

To use the 'Monitoring View', select 'Window -> Tool Windows -> Monitoring View' and the view should display at the bottom of the IDE. The application automatically exposes a URL for retrieving JAMon's performance data via 'http://<host>:<port>/<deployment prefix>-<deployment version>/remote/MonitorSummary'. The 'Monitoring View' is pre-configured to point to the locally exposed URL, but this can be changed by creating a '%HOME DIR%/.midstream/overrides.properties' file with the following entries:

deployment.host=some.host.name
deployment.port=some.port.value

The 'Monitoring View's toolbar provides the following functions:

  • Refresh - Refreshes the current location
  • Back - Navigates back one page
  • Home - Navigates back to the main monitoring page (.../MonitorSummary)
  • Forward - Navigates forward one page

Note: The 'Label' column in the view consists of all the service/client communication calls to '<bean name>.<method name>' and the results are cumulative.

Functional/Integration Testing

MidStream provides a harness (via the MDS Test Runner) for creating/running integration/functional tests against the deployed application. To display the test runner, select 'Window -> Tool Windows -> MDS Test Runner' and the view should display on the right side of the IDE.

The MDS Test Runner enables the creation of three basic types of tests:

  1. Remote Java/HTTP Service - Simulates the client invocation of a Java/HTTP service endpoint via Spring's HTTP invoker
  2. HTTP Post - Performs a simple HTTP post of any text to a service endpoint
  3. Free-Form - Executes any Java-script like code via BeanShell

Each of the three different tests are created via the test runner view and are saved to the project's 'mds' directory in XML format. The tests are selectable and run-able from the view with the output displayable in the 'MDS Test Runner Console' which will be automatically shown at the bottom of the IDE when a test is run.

The view's toolbar provides the following functions:

  • Run MDS Test - the first toolbar button executes the currently selected test
  • New MDS Test - the second toolbar button displays a dialog for creating a new MDS test
  • Modify MDS Test - the third toolbar button displays a dialog for modifying the currently selected test. Only the test's content and endpoint configuration can be changed
  • Delete MDS Test - the fourth toolbar button deletes the currently selected test
  • Refresh - Updates the view's list of tests and endpoint values

Once tests are created, the user can convert the MDS test XML files into simple BeanShell scripts for external execution. To convert a test XML into a BeanShell script:

  1. Right click on the desired test xml in the 'mds' directory and select 'Create BeanShell Script'
  2. Choose a directory to save the scripts to and click the 'Save' button

Remote Java/HTTP Test

The MDS test runner performs introspection on the project's classes for all HTTP service exporters to graphically create request parameters (evaluated by BeanShell) for service invocation.

To create a Java/HTTP test:

  1. Via the 'MDS Test Runner' view, click the second toolbar button (New MDS Test) and select the 'Java/HTTP' tab.
  2. Enter a name for the new test (e.g. HelloServiceTest)
  3. Select the desired service
  4. Select the service method to invoke
  5. For each parameter (if any) in the 'Parameters' table, click the corresponding '...' button in the 'Value' column to create a value for the parameter.
  6. Enter a BeanShell code snippet to construct the parameter object in the 'Edit Parameter' dialog and click the 'OK' button when finished.
  7. Click the 'Save' button to persist the test.

HTTP Post Test

The MDS test runner can post any simple text to a specified URL which is mostly useful for making XML-based Web Service requests to service endpoints. The view provides templates for creating sample XML-RPC, Custom XML/HTTP, and SOAP request packets.

To create a HTTP Post test:

  1. Via the 'MDS Test Runner' view, click the second toolbar button (New MDS Test) and select the 'HTTP Post' tab.
  2. Enter a name for the new test (e.g. HelloXmlTest)
  3. Enter the URL of the service endpoint (e.g. 'http://localhost:8080/app-1.0/remote/RemoteXml')
  4. For the POST payload, either:
    1. Enter the text to post directly in the 'Payload' text box, or
    2. Select a sample template from the '<Select Template>' dropdown and click the 'Template' button. The button will paste the sample template in the 'Payload' text box which can then be customized.
  5. Click the 'Save' button to persist the test.

Free-Form Test

The MDS test runner can execute any Java code that can be evaluated via BeanShell. This method is mostly used to publish messages to a queue/topic and execute any ad-hoc code. The view provides templates for creating sample queue sender, topic publisher, and socket client requests.

To create a Free-Form test:

  1. Via the 'MDS Test Runner' view, click the second toolbar button (New MDS Test) and select the 'HTTP Post' tab.
  2. Enter a name for the new test (e.g. SendQueueMessageTest)
  3. For the script text, either:
    1. Enter the desired code snippet directly to the 'Script' text box, or
    2. Select a sample template from the '<Select Template>' dropdown and click the 'Template' button. The button will paste the sample template in the 'script' text box which can then be customized.
  4. Click the 'Save' button to persist the test.

Deployment

The out-of-the-box deployment unit for MidStream applications is a .war file. In order to utilize runtime configuration values that vary by environment, the application expects a 'MIDSTREAM_ENV' system property to be set with a value of 'Development', 'Test', or 'Production'. For Tomcat, setting of this property is easily done by adding '-DMIDSTREAM_ENV=Development' to the 'CATALINA_OPTS' environment variable.

Best Practices

  1. Whenever a new component is created make sure to flush out the auto-generated unit test to fit your business logic. Test driven development of your application's components will lead to higher quality code.
  2. Once a new service endpoint has been created, it is a good practice to deploy the application and create a functional (MDS) test to validate that the basic infrastructure is working prior to building upon it. This practice will also ensure that valid functional/integration tests are contributed during the development process (which your QA will appreciate!).

Frequently Asked Questions

  1. Why can't I create components if I'm not connected to the net?
    MidStream attempts to download the latest and greatest versions of the dependencies supporting the project and each type of component, as such it is currently necessary to be connected to the Internet/intranet. Future versions will attempt to utilize the local dependency repository if the Internet is not available.
  2. When running the MDS Test Runner I sometimes get OOM errors for permanent memory, what do I do?
    Increase the default -XX:MaxPermSize in IntelliJ's 'idea.exe.vmoptions' (Windows) or 'idea.vmoptions' (Linux) files.
  • No labels