Overview.. 3
Installation. 4
Project Creation. 4
Dependency Management 6
Adding
New Libraries. 7
Updating
Existing Libraries. 7
Removing
Existing Libraries. 7
Component Creation. 7
Service
Components. 8
Java/HTTP. 8
Custom
XML/HTTP. 9
XML-RPC.. 10
SOAP. 10
JMS
Message Receiver 11
Scheduled
Service. 12
Client/Connector
Components. 12
Configuration
Bean. 12
Cache
Manager Bean. 13
Data
Access Object 13
XML-RPC
Client 14
Socket
Client 14
HTTP
Client 15
JMS
Message Producer 16
SOAP
Web Service Client 16
Application Context Management 17
Application Monitoring. 18
Functional/Integration Testing. 19
Remote
Java/HTTP Test 20
HTTP
Post Test 20
Free-Form
Test 21
Deployment 21
Best Practices. 21
Frequently Asked Questions. 21
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:
- 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
- Messaging
– Utilizes Spring’s asynchronous message receiving support classes for
creating POJO messaging receivers for both JMS queues and topics.
- 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:
- Configuration
– Utilizes Commons Configuration to encapsulate application data in XML
format that can hot deployed and reloaded
- Caching
– Utilizes Ehcache to provide a caching mechanism for application
components
- Data
Access Objects – Utilizes Spring JDBC and the DAO pattern to encapsulate
accessing a DBMS.
- XML-RPC
Client – Utilizes Apache’s XML-RPC library to create a client POJO for a
remote XML-RPC service
- Socket
Client – Creates a client POJO for making general secure/non-secure socket
communication calls
- HTTP
Client – Utilizes Commons HttpClient to create a client POJO for making
HTTP GET/POST requests
- JMS
Message Production – Utilizes Spring’s JMS template support classes to
create a POJO for producing JMS queue/topic messages
- SOAP Web
Service Client – Utilizes Apache Axis to create POJO clients for
interacting with SOAP exposed Web Services
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.
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:
<settings>
<proxies>
<proxy>
<active>true</active>
<protocol>http</protocol>
<host>your.proxy.host</host>
<port>80</port>
<username>your.proxy.username</username>
<password>your.proxy.password</password>
<nonProxyHosts>localhost</nonProxyHosts>
</proxy>
</proxies>
</settings>
To create a new project:
- Select
‘File -> New MidStream Project…’
- Enter
a name for the project (e.g. ‘MyProject’)
- Enter
a location for the project (e.g. ‘c:\temp’). Note that you can use the
browse button (‘…’) to select a location.
- 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.
- 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.
- 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.
- Click
the ‘OK’ button to create the project.
- Open
the ‘Ant View’ and click the ‘+’ button to add the project’s build file
- Click
‘Ctrl + 2’ to expand the tree view to the project’s directory
- Select
the ‘build.xml’ under the project’s directory and click the ‘OK’ button
- Right
click on the project’s named node in the ‘Ant View’ and select ‘Properties
-> Additional Classpath -> Add’
- Click
‘Ctrl + 2’, expand the ‘lib’ directory under the project, select the JUnit
library, and click ‘OK’.
- 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
|
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:
- Right
click on the (top level node) project in the ‘Project View’
- Select
‘Project Dependencies…’ menu item
- 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.
- Check
the version that you wish to utilize
- Repeat
1 & 2 for all libraries that you wish to add
- Check
the ‘Add to Build Path’ box if you wish for the library to be placed on
the project’s classpath for IntelliJ
- 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’.
- Click
the ‘OK’ button to add the dependencies.
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.
- 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.
- Click
the ‘OK’ button to update the selected dependencies
- 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.
- 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)
- 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
- Click
the ‘OK’ button to update the selected dependencies
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:
- Right
click on the POJO Java source to create the definition for and select
‘Create Bean Definition’
- Enter
a name for the bean (e.g. HelloBean)
- For
each property listed in the ‘Bean Properties’ table click the
corresponding ‘…’ button to set a value for it.
- Select
the tab of the type of property you wish to add, select:
i.
‘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.
ii.
‘Value’ to add a primitive value property
1. Enter
the desired value
2. Select
the type of the value from the dropdown
iii.
‘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:
a. the relative key/value pairs
b. a reference’s name in the value column and
checking the corresponding ‘Ref’ box
- Click
the ‘OK’ button to set the property’s value
- Repeat
step three as necessary
- Click
the ‘OK’ button to create the bean definition.
To create new remote Java/HTTP service:
- Right
click on the (top-level node) project in the ‘Project View’ and select ‘New
-> Remote Service’
- Enter
the Java package name of the new service POJO (e.g. com.foo.bar)
- Enter
the name of the service (e.g. HelloService)
- Select
‘Java/HTTP’ as the ‘Remoting Type’
- 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:

To create a new remote service that accepts/returns XML
based on a custom structure:
- Right
click on the (top-level node) project in the ‘Project View’ and select
‘New -> Remote Service’
- Enter
the Java package name of the new service POJO (e.g. com.foo.bar)
- Enter
the name of the service (e.g. HelloService)
- Select
‘Custom XML/HTTP’ as the ‘Remoting Type’
- 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).
- 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).
- 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)
- 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.
To create new remote XML-RPC service:
- Right
click on the (top-level node) project in the ‘Project View’ and select
‘New -> Remote Service’
- Enter
the Java package name of the new service POJO (e.g. com.foo.bar)
- Enter
the name of the service (e.g. HelloService)
- Select
‘XML-RPC’ as the ‘Remoting Type’
- 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
To create new remote SOAP Web Service:
- Right
click on the (top-level node) project in the ‘Project View’ and select
‘New -> Remote Service’
- Enter
the Java package name of the new service POJO (e.g. com.foo.bar)
- Enter
the name of the service (e.g. HelloService)
- Select
‘SOAP’ as the ‘Remoting Type’
- 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).
To create a new JMS message receiver:
- Right
click on the (top-level node) project in the ‘Project View’ and select
‘New -> JMS Receiver’
- Enter
the Java package name of the new POJO receiver (e.g. com.foo.bar)
- Enter
the name of the receiver (e.g. HelloReceiver)
- Enter
the number of concurrent listeners the application should support. The
default is ‘1’.
- Enter
the destination’s name. This is the name of the queue/topic that the receiver
will be consuming (e.g. MyQueue)
- Select
the destination type (queue or topic).
- Enter
a user name to be used to connect to the queue/topic if one is required
- Enter
a password to be used to connect to the queue/topic if one is required
- Enter
the JNDI name of the connection factory to use. This name will be looked
up from the configured JNDI context. (e.g. ConnectionFactory)
- Enter
the initial naming factory (e.g. org.apache.activemq.jndi.ActiveMQInitialContextFactory)
- Enter the provider URL of the queue/topic. (e.g. tcp://hostname:61616)
- Enter the security principal (i.e. user name/role) to
be used to lookup the destination and connection factory from JNDI
- Enter the security credentials (i.e.
password/authentication) to be used to lookup the destination and
connection factory from JNDI
- 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.
To create a new scheduled service:
- Right
click on the (top-level node) project in the ‘Project View’ and select
‘New -> Scheduled Service’
- Enter
the Java package name of the new POJO scheduled service (e.g. com.foo.bar)
- Enter
the name of the scheduled service (e.g. HelloSchedule)
- 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)
- Enter
the scheduler’s period. This is the frequency at which the scheduler
should run the service. (e.g. ‘60000’ for every minute)
- 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.
To create a configuration bean for your application:
- Right
click on the (top-level node) project in the ‘Project View’ and select
‘New -> Configuration Bean’
- 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.
To create a cache manager bean for your application:
- Right
click on the (top-level node) project in the ‘Project View’ and select
‘New -> Cache Bean’
- 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.
To create a cache manager bean for your application:
- Right
click on the (top-level node) project in the ‘Project View’ and select
‘New -> Data Access Object (DAO)’
- Enter
the Java package name of the new POJO DAO (e.g. com.foo.bar)
- Enter
the name of the DAO (e.g. HelloDAO)
- Enter
the JNDI name that the desired data source is bound to (e.g. jdbc/TestDS).
- Enter
the SQL statement (with bind variables as necessary) to be executed by the
DAO.
- 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.
To create a new XML-RPC client bean:
- Right
click on the (top-level node) project in the ‘Project View’ and select
‘New -> XML-RPC Client’
- Enter
the Java package name of the new POJO client (e.g. com.foo.bar)
- Enter
the name of the client (e.g. HelloClient)
- Enter
the name of the XML-RPC method to invoke (e.g. execute).
- Enter
the connection timeout. This is how long the client will wait to establish
a connection with the service. (e.g. 10)
- Enter
the read timeout. This is how long the client will wait for a response
while communicating with the service. (e.g. 10)
- 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
To create a new XML-RPC client bean:
- Right
click on the (top-level node) project in the ‘Project View’ and select
‘New -> Socket Client’
- Enter
the Java package name of the new POJO client (e.g. com.foo.bar)
- Enter
the name of the client (e.g. HelloClient)
- Check
the ‘Is Secure?’ box if the communication should use SSL.
- Enter
the host to connect to. This can be a host name or IP (e.g. 127.0.0.1)
- Enter
the port to connect to (e.g. 80)
- Enter
the connection timeout. This is how long the client will wait to establish
a connection with the service. (e.g. 10)
- Enter
the read timeout. This is how long the client will wait for a response
while communicating with the service. (e.g. 10)
- Enter
the location of the key store if certificates are necessary.
- Enter
the type of the key store (e.g. JKS)
- Enter
the key’s algorithm (e.g. DCA)
- Enter
the name of the secure protocol (e.g. SSLv3)
- 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
To create a new HTTP client bean:
- Right
click on the (top-level node) project in the ‘Project View’ and select
‘New -> HTTP Client’
- Enter
the Java package name of the new POJO client (e.g. com.foo.bar)
- Enter
the name of the client (e.g. HelloClient)
- Enter
the connection timeout. This is how long the client will wait to establish
a connection with the service. (e.g. 10)
- Enter
the read timeout. This is how long the client will wait for a response
while communicating with the service. (e.g. 10)
- 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
To create a new JMS message producer:
- Right
click on the (top-level node) project in the ‘Project View’ and select
‘New -> JMS Message Producer’
- Enter
the Java package name of the new POJO producer (e.g. com.foo.bar)
- Enter
the name of the producer (e.g. HelloProducer)
- Enter
the destination’s name. This is the name of the queue/topic that the producer
will be publishing to (e.g. MyQueue)
- Select
the destination type (queue or topic).
- Enter
a user name to be used to connect to the queue/topic if one is required
- Enter
a password to be used to connect to the queue/topic if one is required
- Enter
the JNDI name of the connection factory to use. This name will be looked
up from the configured JNDI context. (e.g. ConnectionFactory)
- Enter
the initial naming factory (e.g. org.apache.activemq.jndi.ActiveMQInitialContextFactory)
- Enter the provider URL of the queue/topic. (e.g. tcp://hostname:61616)
- Enter the security principal (i.e. user name/role) to
be used to lookup the destination and connection factory from JNDI
- Enter the security credentials (i.e. password/authentication)
to be used to lookup the destination and connection factory from JNDI
- 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.
To create a new SOAP Web Service client bean:
- Right
click on the (top-level node) project in the ‘Project View’ and select
‘New -> SOAP Web Service Client’
- Enter
the Java package name of the new POJO client (e.g. com.foo.bar)
- Enter
the name of the client (e.g. HelloClient)
- Enter
the URL of the service’s WSDL (e.g. ‘file:/tmp/a.wsdl’ or
‘http://host/svc/wsdl’)
- Enter
the Java package name for the generated service stubs (from the WSDL)
- Enter
the read timeout. This is how long the client will wait for a response
while communicating with the service. (e.g. 10)
- 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
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:
- Navigate
to the application’s context file
- Navigate
to the bean’s implementation class
- Add
properties to the selected bean. This enables the wiring together of beans
in the context view.
To save the view as an image:
- Click
the third toolbar button (Save As GIF)
- Choose
the directory to save the image to
- Enter
the file name of the image
- Click
the ‘Save’ button to save the image
To add properties to a bean and/or wire beans together:
- Right
click on the bean of interest and select ‘Source -> Add Property’
- Enter
the property name to be added to the bean (e.g. newProp)
- Check
the ‘Add Getter/Setter…’ box to add getter/setter methods to the bean’s
Java source file
- Select
the tab of the type of property you wish to add, select:
- ‘Reference’
to add a dependency upon another bean.
i.
Select the desired bean from the ‘Bean:’ dropdown
ii.
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.
- ‘Value’
to add a primitive value property
i.
Enter the desired value
ii.
Select the type of the value from the dropdown
- ‘Collection’
to add a collection property
i.
Select the type of the collection (Properties, List, Map, Set)
ii.
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
- 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.
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.
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:
- Remote
Java/HTTP Service – Simulates the client invocation of a Java/HTTP service
endpoint via Spring’s HTTP invoker
- HTTP
Post – Performs a simple HTTP post of any text to a service endpoint
- 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:
- Right
click on the desired test xml in the ‘mds’ directory and select ‘Create
BeanShell Script’
- Choose
a directory to save the scripts to and click the ‘Save’ button
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:
- Via
the ‘MDS Test Runner’ view, click the second toolbar button (New MDS Test)
and select the ‘Java/HTTP’ tab.
- Enter
a name for the new test (e.g. HelloServiceTest)
- Select
the desired service
- Select
the service method to invoke
- For
each parameter (if any) in the ‘Parameters’ table, click the corresponding
‘…’ button in the ‘Value’ column to create a value for the parameter.
- Enter
a BeanShell code snippet to construct the parameter object in the ‘Edit
Parameter’ dialog and click the ‘OK’ button when finished.
- Click
the ‘Save’ button to persist the 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:
- Via
the ‘MDS Test Runner’ view, click the second toolbar button (New MDS Test)
and select the ‘HTTP Post’ tab.
- Enter
a name for the new test (e.g. HelloXmlTest)
- Enter
the URL of the service endpoint (e.g. http://localhost:8080/app-1.0/remote/RemoteXml)
- For
the POST payload, either:
- Enter
the text to post directly in the ‘Payload’ text box, or
- 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.
- Click
the ‘Save’ button to persist the 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:
- Via
the ‘MDS Test Runner’ view, click the second toolbar button (New MDS Test)
and select the ‘HTTP Post’ tab.
- Enter
a name for the new test (e.g. SendQueueMessageTest)
- For
the script text, either:
- Enter
the desired code snippet directly to the ‘Script’ text box, or
- 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.
- Click
the ‘Save’ button to persist the test.
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.
- 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.
- 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!).
- 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.
- 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.