Spring.NET 1.3.0 RC1 SDK Reference Documentation

The Spring.NET Framework SDK Reference

Introduction

Developing software applications is hard enough even with good tools and technologies. Spring provides a light- weight solution for building enterprise-ready applications. Spring provides a consistent and transparent means to configure your application and integrate AOP into your software. Highlights of Spring's functionality are providing declarative transaction management for your middle tier as well as a full-featured ASP.NET framework.

Spring could potentially be a one-stop-shop for many areas of enterprise application development; however, Spring is modular, allowing you to use just those parts of it that you need, without having to bring in the rest. You can use just the IoC container to configure your application and use traditional ADO.NET based data access code, but you could also choose to use just the Hibernate integration code or the ADO.NET abstraction layer. Spring has been (and continues to be) designed to be non-intrusive, meaning dependencies on the framework itself are generally none (or absolutely minimal, depending on the area of use).

This document provides a SDK reference to Spring's features. If you have any requests or comments, please post them on the user mailing list or on the support forums at http://forum.springframework.net

For obtaining the latest version of the Spring.NET Framework and this SDK reference, please visit http://www.springframework.net

A sample link to a namespace

A sample link to a class

Assemblies

Assembly Description
Spring.Core

The Spring.Core assembly provides an implementation of an Inversion of Control container. 

Inversion of Control (IoC) containers provide a simple but powerful means to create and configure properties of objects in your application.  These properties maybe simple types, such as strings or integers but much of the power of an IoC container comes from the ability to set properties that are references to other objects in your application, i.e. an objects dependencies. 

An introductory article to IoC containers can be found in the September 2005 edition of MSDN Magazine.  Links to additional introductory material on IoC containers can be found on the Spring.NET or Spring Framework web sites.

The design of Spring.NET's IoC container is such that your application objects configured by the IoC container almost always to not need to depend on any classes or interfaces contained in this namespace. 

However, you may find it useful to reference this assembly as it contains some general framework style classes   These range from Spring.Expressions that provides evaluation of object graph expressions to Spring.Util that provides various Reflection, String, and XML utility functions.

Inversion of Control (IoC) containers provide a non-invasive means to configure the dependency of objects in your application.  A more detailed introduction to IoC containers can be found is this article by Martin Fowler which uses a simple movie search application as a means to demonstrate the IoC container. 

This example implemented using Spring.NET's IoC is available as part of the the Spring.NET distribution and documented as the MovieFinder Quickstart.

Spring.Aop

Aspect-Oriented Programming (AOP) complements OOP by providing another way of thinking about program structure. Whereas OO decomposes applications into a hierarchy of objects, AOP decomposes programs into aspects or concerns.  This enables the modularization of concerns such as transaction management that would otherwise cut across multiple objects (such concerns are often termed crosscutting concerns).

Spring AOP offers:

  • Introduction support
  • A Pointcut abstraction, supporting "static" pointcuts  (class and method-based) and "dynamic" pointcuts (also considering method arguments).
  • A full range of advice types, including around, before, after returning and throws advice.
  • Extensibility allowing arbitrary custom advice types to be plugged in without modifying the core framework.

    Spring AOP can be used programmatically or (preferably) integrated with the Spring IoC container.
Spring.Web

Spring.NET's web application framework aims to increase your productivity writing ASP.NET WebForms applications. It offers a unique value proposition to creating ASP.NET applications not found in other .NET web frameworks.

The goal of the framework is to make it easy to write 'thin and clean' web applications. By thin, what is meant is that the WebForm's responsibility is to act as adapter between the HTML based world of the web and the oo world of your application. The application layer your web form communicates with is where the business logic resides, not in the web tier. By 'clean' what is meant that the web framework should have a good separation of concerns, leading ideally to an event-handler that does not contain any reference to UI elements. This makes it possible to test your event handler code in integration style tests. Last but not least, Spring's web framework reduces the incidental complexity of common tasks in the web tier, for example the conversion of HTML control data to object and then vice-versa after the request has been processed by the application layer.

Highlights of Spring's Web framework are

  • Dependency Injection for all ASP.NET artifacts. This includes pages and user controls but also modules, providers and HTTP handlers. Your pages, controls, etc., do not have any Spring dependencies in order to be configured via dependency injection.

  • Bi-directional data binding. This allows you to declaratively define the data that will be marshaled out of your html/user controls and into a data model that in turn is generally submitted to the application layer. After the data model is updated in the application layer, those changes are automatically reflected in the html/user controls on post back. This removes large amounts of tedious, error prone boilerplate code.

  • Web object scopes. Object definitions can be defined at the application, session or request scope. This makes it easy to inject, say a session scoped shopping cart, into your page without having to do any lower level programming

  • Data Model Management. While ASP.NET managed the view state of your form, it does not offer facilities to manage the data model that you build up to submit to the application layer. Spring provides a mechanism similar to view state to help manage your data model.

  • UI agnostic validation framework. Declaratively define complex validation rules, for example that take into account complex relationships in your data model. Error controls are provided to easily render validation failure. This allows you to centralize your validation logic and also reuse it on the server side, for example using parameter validation advice described in the aspect library chapter

  • Externalized page navigation through 'result mapping'. Instead of hard coding urls and data to direct where a page should go next, result mappings are externally defined and configured that associate logical names and a URL (+ data). This also allows to encryption of values that are sent via Response.Redirect.

  • Improved localization and master page support - Advanced localization features (including image localization) as well as declarative configuration of what mater page to apply to different parts of your web application are easy to perform.

All you know about ASP.NET development still applies, Spring's approach is to 'embrace and extend' the basic ASP.NET programming model so you can be as productive as possible.

The ASP.NET Web Framework section of the reference documentation and QuickStart applications (SpringAir and Spring.WebQuickStart)  are the best places to get started using the functionality contained in Spring.Web.

Spring.Web.Extensions

Spring's ASP.NET AJAX integration allows for a plain .NET object (PONO), that is one that doesn't have any attributes or special base classes, to be exported as a web service, configured, via dependency injection, 'decorated' by applying AOP, and then exposed to client side java script.

The reference documentation and sample application, listed under the shortcut 'AJAX', directory examples\Spring\Spring.Web.Extensions.Example, are the best places to get started using the functionality contained in Spring.Web.Extensions.

Spring.Services

The goal of Spring's integration with distributed technologies is to adapt plain .NET objects so they can be used with a specific distributed technology. This integration is designed to be as non-intrusive as possible. If you need to expose an object to a remote process then you can define an exporter for that object. Similarly, on the client side you define an corresponding endpoint accessor. Of course, the object's methods still need to be suitable for remoting, i.e. coarse grained, to avoid making unnecessary and expensive remote calls.

Since these exporters and client side endpoint accessors are defined using meta data for Spring IoC container, you can easily use dependency injection on them to set initial state and to 'wire up' the presentation tier, such as web forms, to the service layer. In addition, you may apply AOP aspects to the exported classes and/or service endpoints to apply behavior such as logging, security, or other custom behavior that may not be provided by the target distributed technology. The Spring specific terminology for this approach to object distribution is known as Portable Service Abstractions (PSA). As a result of this approach, you can decide much later in the development process the technical details of how you will distribute your objects as compared to traditional code centric approaches. Changing of the implementation is done though configuration of the IoC container and not by recompilation. Of course, you may choose to not use the IoC container to manage these objects and use the exporter and service endpoints programatically.

Supported technologies are:

  • .NET Remoting
  • EnterpriseServices
  • .ASMX WebServices
  • WCF Services

Please refer to the Portable Service Abstraction QuickStart application distributed with Spring and described in the reference docs here.  The reference docs are also a good place to get started.

Spring.Data

The Spring.Data assembly provides an implementation of best practice approaches to data access.

Specifically, it contains an abstraction for transaction management that provides the following benefits

  • Provides a consistent programming model across different transaction APIs such as ADO.NET, EnterpriseServices, System.Transactions, and NHibernate.
  • Support for declarative transaction management with any of the above data access technologies
  • Provides a simple API for programmatic transaction management
  • Integrates with Spring's high level persistence integration APIs such as AdoTemplate.

 

Spring.Data also contains an abstraction for data access via ADO.NET that provides the following benefits and features

  • Consistent and comprehensive database provider interfaces for both .NET 1.1 and 2.0

  • Integration with Spring's transaction management features.

  • 'One-liner' implementations for the most common database usage patterns lets you focus on the 'meat' of your ADO.NET code.

  • Template style use of DbCommand that removes the need to write typical ADO.NET boiler-plate code.

  • Easy database parameter creation/management

  • Provider independent exceptions with database error codes and higher level DAO exception hierarchy.

  • Centralized resource management for connections, commands, data readers, etc.

  • Simple DataReader to Object mapping framework.

 

For more information refer to the Getting Started section within this documentation and the reference documentation, the latest copy of which can be found on the Spring.NET web site.

Foundational support for Data Access, providing and ADO.NET Framework, declarative transaction management, and exception translation features.

The reference documentation and Spring.DataQuickStart are the best places to get started using the functionality contained in Spring.Data.

Spring.Data.NHibernateXX

The Spring Framework provides integration with NHibernate in terms of resource management, DAO implementation support, and transaction strategies. For example for NHibernate, there is first-class support with lots of IoC convenience features, addressing many typical NHibernate integration issues. All of these support packages for O/R (Object Relational) mappers comply with Spring's generic transaction and DAO exception hierarchies. There are usually two integration styles: either using Spring's DAO 'templates' or coding DAOs against the 'plain' NHibernate APIs. In both cases, DAOs can be configured through Dependency Injection and participate in Spring's resource and transaction management.

You can use Spring's support for NHibernate without needing to use Spring IoC or transaction management functionality. The NHibernate support classes can be used in typical 3rd party library style. However, usage inside a Spring IoC container does provide additional benefits in terms of ease of configuration and deployment; as such, most examples in this section show configuration inside a Spring containe

This assembly provides integration of NHibernate 2.0 with Spring concepts.

Contains SessionFactory helper classes, a template plus callback for Hibernate access, and an implementation of Spring's transaction SPI for local Hibernate transactions.

The Spring.Data.NHibernate.Northwind Quick Start application as well as the reference documentation chapter on NHibernate integration are good places to get started.

Spring.Testing.NUnit While dependecy injection generally leads to classes that are easier to unit test, precisely becuase there are no hidden dependencies in the code and an objects collaborators can be coded explicitly in the test, it is also important to be able to perform some integration testing enabling you to test things such as:
  • The correct wiring of your Spring IoC container contexts.

  • Data access using ADO.NET or an ORM tool. This would include such things such as the correctness of SQL statements / or NHibernate XML mapping files.

The Spring Framework provides first class support for integration testing in the form of the classes that are packaged in the Spring.Testing.NUnit.dll library

Superclasses for tests requiring Spring application contexts, including support for transactional execution of test cases,
with automatic rollback on completion. Useful as base classes for application-specific tests.

The superclasses in this package are ideal for integration testing. Unit testing should not normally involve the Spring container,
but should test classes in isolation.

The reference documentation is the best place to get started using Spring and NUnit together.  If you are not familiar with NUnit, check out the NUnit website at www.nunit.org

Spring.Messaging

The goals of Spring's MSMQ 3.0 messaging support is to raise the level of abstraction when writing MSMQ applications. The System.Messaging API is a low-level API that provides the basis for creating a messaging application. However, 'Out-of-the-box', System.Messaging leaves the act of creating sophisticated multi-threaded messaging servers and clients as an infrastructure activity for the developer. Spring fills this gap by proving easy to use helper classes that makes creating an enterprise messaging application easy. These helper classes take into account the nuances of the System.Messaging API, such as its lack of thread-safety in many cases, the handling of so-called 'poison messages' (messages that are endlessly redelivered due to an unrecoverable exception during message processing), and combining database transactions with message transactions. Other goals of Spring's MSMQ messaging support are to support messaging best practices, in particular encouraging a clean architectural layering that separates the messaging middleware specifics from the core business processing.

Spring's approach to distributed computing has always been to promote a plain old .NET object approach or a PONO programming model. In this approach plain .NET objects are those that are devoid of any reference to a particular middleware technology. Spring provides the 'adapter' classes that converts between the middleware world, in this case MSMQ, and the oo-world of your business processing. This is done through the use of Spring's MessageListenerAdapter class and IMessageConverters.

Contains integration classes for MSMQ allowing for 'Spring-style' MSMQ access.

Please refer to the MSMQ QuickStart application that is part of the distribution in the examples directory.  If installing using the Windows installer you can find the example under the Spring.NET menu.  Documentation for the quickstart example can be found online here as well as in the reference docs included in the distribution.  There is also the section "A quick tour for the impatient" in the reference docs that is a good introduction.

Spring.Messaging.Nms

The goal of Spring's messaging is to increase your productiviity when writing an enterprise strength messaging middleware applications. Spring achieves these goals in several ways. First it provides several helper classes that remove from the developer the incidental complexity and resource management issues that arise when using messaging APIs. Second, the design of these messaging helper classes promote best practices in designing a messaging application by promoting a clear separation between the messaging middleware specific code and business processing that is technology agnostic. This is generally referred to a "plain old .NET object" (or PONO) programming model.

Integration classes or Apache ActiveMQ (NMS) providing helper classes for sending and receiving messages synchronously as well as multi-threaded consumption of messages asynchronously. Provides support for PONO based message callbacks.

The quick start application, Spring.NmsQuickStart as well as the section in the reference docs are good places to get started.

Spring.Messaging.Ems

As with the Apache ActiveMQ integration classes, The goal of Spring's TIBCO EMS support is to increase your productiviity when writing TIBCO EMS based applications.

The quick start application, Spring.EmsQuickStart as well as the section in the reference docs are good places to get started.

Spring.Scheduling.Quartz

For convenience purposes, Spring offers a couple of classes that simplify the usage of Quartz within Spring-based applications. For example a convenience class for the Quartz Scheduler is available that allows you to invoke a method of an existing target object.

Support for configuring Quartz.NET scheduler objects in a Spring context.

The quick start application Spring.Scheduling.Quartz.Example, as well as the Quartz section in the reference docs are good places to get started.

Spring.Template.Velocity

For convenience purposes, Spring offers a couple of classes that simplify the usage of configuring a NVelocity engine within Spring-based applications.

The Quartz section in the reference docs is a good place to get started.