Service Registry

Mule ESB Enterpise

Service Registry User’s GuideVersion 1.5.3July 2009

For a quick start, see page 7

Confidential

The ideas contained in this publication are subject to use and disclosure restrictions as set forth in the license agreement.

Copyright

Copyright 2003-2009, MuleSource, Inc. All rights reserved. No part of this publication may be copied or distributed, transmitted, transcribed, stored in a retrieval system, or translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, manual, optical, chemical or otherwise; or disclosed to third parties without the express written permission of MuleSource, Inc.

Disclaimer

Information in this document is subject to change without notice and does not represent a commitment on the part of MuleSource, Inc. The software described in this document is furnished under a license agreement or nondisclosure agreement. The software may be used or copied only in accordance with the terms of the agreement. It is against the law to copy the software on any medium except as specifically allowed in the agreement.

In addition, MuleSource Inc makes no representation or warranties either express or implied, with respect to this manual and accompanying software and specifically disclaim any implied warranties of merchantability or fitness for any particular purpose. This manual and accompanying software are sold “as is” and MuleSource, Inc will in no event be liable for direct, indirect, incidental or consequential damages resulting from any defect, error or failure to perform except as expressly set forth in the license agreement.

Trademarks

All product names, other than Mule, are trademarks of their respective companies.

Part number: G15en_us2009.7.1

Service Registry User’s Guide 3

Table of Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7Who Should Read This Guide? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7What’s the Fastest Way Through This Guide? . . . . . . . . . . . . . . . . . . . . 7Typographic Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8MuleSource Technical Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Chapter 1 Introduction to the Service Registry . . . . . . . . . . . . . . . . . . . . . . . 9

What is SOA Governance? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9SOA Governance Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9How the Service Registry Helps You. . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Contract Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Service Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10Staged Deployments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Improved Interoperability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11Simplified Mule Application Deployment. . . . . . . . . . . . . . . . . . . 11Collaboration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11The Service Registry in Your Workflow. . . . . . . . . . . . . . . . . . . . . 12

Service Registry Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Artifact Management and Organization . . . . . . . . . . . . . . . . . . . . 12Easy Access to Important Artifact Details . . . . . . . . . . . . . . . . . . . 13Metadata. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Searching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Lifecycle Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Dependency Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Policy Enforcement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Application Deployment Management (Mule NetBoot) . . . . . . . . 14Extensibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14Activity Monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Atom Publishing Protocol API . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Integration with Mule, CXF, and Spring . . . . . . . . . . . . . . . . . . . . 15Federation Capabilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4 Service Registry User’s Guide

Table of Contents

Other Exclusive Features in the Service Registry . . . . . . . . . . . . . . 16Service Registry Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Additional Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Chapter 2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19Environment Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Downloading the Service Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Running the Standalone Service Registry . . . . . . . . . . . . . . . . . . . . . . . 20Configuring the Service Registry WAR . . . . . . . . . . . . . . . . . . . . . . . . 21

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Using the Configuration Utility . . . . . . . . . . . . . . . . . . . . . . . . . . 22

Logging Into the Service Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

Chapter 3 Using the Service Registry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

Viewing the Repository Contents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25Managing Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Using Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26Applying Policy Enforcement . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Managing Artifacts and Entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28Types of Artifacts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Viewing Artifact and Entry Details . . . . . . . . . . . . . . . . . . . . . . . . 29Working with Metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Managing Lifecycles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Managing Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Searching Artifacts and Entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32Saving Searches as Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Editing Multiple Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Subscribing to Change Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Chapter 4 Integrating Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Installing the Plug-ins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Mule 2.x Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Starting Mule from Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37


Table of Contents

Starting Mule from Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Mule 2.x Plug-in Configuration Reference . . . . . . . . . . . . . . . . . . 38

Mule 1.x Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Starting Mule from Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Starting Mule from Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39Mule 1.x Plug-in Configuration Reference . . . . . . . . . . . . . . . . . . 40

Apache CXF Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Integrating from the XML Configuration . . . . . . . . . . . . . . . . . . . 41Integrating from the API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Spring Integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43Publishing a Maven Project to the Service Registry. . . . . . . . . . . . . . . . 43

Adding the Galaxy Repository to the POM . . . . . . . . . . . . . . . . . 44Configuring the Plug-in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Configuring Useful Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46Configuring Security Information. . . . . . . . . . . . . . . . . . . . . . . . . 46Additional Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . 47

Chapter 5 Administering the Service Registry . . . . . . . . . . . . . . . . . . . . . . . 48

Managing Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48Managing Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Managing Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49Enabling Authentication Through LDAP . . . . . . . . . . . . . . . . . . . 51

Managing Artifact Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56Managing Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

XPath Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57XQuery Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58Working with Indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Managing Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Managing Lifecycles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62Managing Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63Creating Remote Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Monitoring Registry Activity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Installing Your Service Registry License . . . . . . . . . . . . . . . . . . . . . . . . 66

Chapter 6 Working with Scripts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Creating a Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Modifying a Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68


Table of Contents

Scheduling a Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68Cron Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Event Listener . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71Notification Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72Replicating Workspaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Chapter 7 Using Mule NetBoot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76

Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76Publishing Applications to the Service Registry . . . . . . . . . . . . . . . 76Setting Up Mule NetBoot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77Starting Mule via Mule NetBoot . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Installing Mule NetBoot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78Running Mule NetBoot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79

Specifying the Mule Configuration File. . . . . . . . . . . . . . . . . . . . . 79Mule NetBoot Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80Booting from Multiple Workspaces. . . . . . . . . . . . . . . . . . . . . . . . 80

Caching and Offline Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81Mule NetBoot and JMX. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81

Appendix A Galaxy Query Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

Basic Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82Artifact Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83Statement Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84


Preface

The Service Registry User’s Guide introduces the service registry for Mule ESB Enterprise. It provides the conceptual information and context that everyone from decision makers to administrators need to get started with planning and implementing the service registry.

Who Should Read This Guide?This guide is intended for the following audiences:

Architects who need to plan how they will use the service registry with their other applications

Governance and control administrators who will apply policies to artifacts Administrators who will maintain and troubleshoot the service registry

What’s the Fastest Way Through This Guide?This section describes what you should read based on your role. All users should refer to the Glossary on page 7 for definitions of common terms.

Getting a Quick Start

If your role is... Read...

Architect responsible for designing the system

Chapter 1, “Introduction to the Service Registry” Chapter 2, “Getting Started” Chapter 3, “Using the Service Registry” Chapter 4, “Integrating Applications”

Governance and control administrators

Chapter 1, “Introduction to the Service Registry” Chapter 2, “Getting Started” Chapter 3, “Using the Service Registry” Chapter 7, “Using Mule NetBoot”

Typographic Conventions Preface


Typographic ConventionsThe following table describes the typographic conventions used in the Mule ESB Enterprise documentation:

MuleSource Technical SupportIf you have a paid subscription to MuleSource, you can view the knowledge base and get assistance with the service registry, Mule ESB Enterprise, and other MuleSource offerings by logging in to http://mulesupport.mulesource.com. For information on purchasing a subscription, contact MuleSource by phone at 1-877-MULE-OSS or by email at [email protected].

Developer responsible for extending the service registry

Chapter 1, “Introduction to the Service Registry” Chapter 2, “Getting Started” Chapter 6, “Working with Scripts” Appendix A, “Galaxy Query Language”

Administrator responsible for maintaining the service registry

Chapter 1, “Introduction to the Service Registry” Chapter 2, “Getting Started” Chapter 5, “Administering the Service Registry”

Getting a Quick Start (Continued)

If your role is... Read...

Typeface Meaning Example

AaBbCc123 Files and directory names, parameters, command lines, and code examples.

Edit the information in applicationContext.xml

AaBbCc123 Placeholder text that you change. http://serverName/galaxy

AaBbCc123 A live link to a web site, email address, or another section in the document

See page 8

AaBbCc123 The names of user interface controls, menus, and menu items.

Choose File > Edit.

http://mulesupport.mulesource.com

mailto:[email protected]


Chapter 1

Introduction to the Service Registry

As your organization increases its number of applications and services, integration among them becomes more complex, and the need for centralized governance and collaboration becomes more urgent. The service registry for Mule ESB Enterpriseis a service-oriented architecture (SOA) governance platform with an integrated registry/repository. This chapter describes SOA governance, why it matters, and how the service registry fits into the picture.It contains the following sections:

“What is SOA Governance?” on page 9 “SOA Governance Tools” on page 9 “How the Service Registry Helps You” on page 10 “Service Registry Features” on page 12 “Service Registry Architecture” on page 17 “Additional Resources” on page 17

What is SOA Governance?At a very high level, governance is the process of promoting desired behavior through the use of rules, tools, and/or people. For example, local governments promote safe driving through laws, traffic signals, and police. With information technology (IT), some examples of governance are encouraging reuse of existing software/hardware assets, ensuring compliance with laws, and conforming to best practices for service interoperability.

SOA Governance ToolsSOA governance tools are an important part of an IT governance plan. The tools help you to do the following:

Lower overall development costs and increase service reuse Gain visibility and control over service lifecycles and policy compliance

How the Service Registry Helps You Chapter 1 Introduction to the Service Registry


Shorten project cycle times and time to value Improve collaboration across departments Create a record of all changes for audit purposes Gain visibility into consumers of your services and or artifacts so you can make intelligent

decisions about future development needs.

To maximize the effectiveness of your SOA governance tools, it is also extremely important to implement the proper policies and processes inside your organization. The service registry helps you with that implementation.

How the Service Registry Helps YouThe service registry can become a central part of your workflow, ensuring that all parties adhere to your policies and processes. The following sections dive deeper into some examples of how you can use the service registry inside your organization.

Contract Management

When you have hundreds of services across your organization, it can be difficult to know which services are available and if they’re usable. The service registry allows you to index your WSDL contracts, XML schemas, and even your services that are defined in Java interfaces and classes, making them easily searchable. Your services become easier to consume and benefit from the increased reuse. You can also attach lifecycle information, allowing you to determine if the service is usable in your production application.

Service Discovery

With your service contracts in a central location, service discovery becomes easier. If you are using WSDL-based services, you can use the WSDL in the repository as your source of truth for the location of the actual service endpoint. You can also use the service registry’s powerful artifact metadata system to store and update your service location. You can write a simple query using the AtomPub HTTP API to determine the location of your service.


Chapter 1 Introduction to the Service Registry How the Service Registry Helps You

Staged Deployments

Most SOA projects are deployed in phases: development, test, and production. The service registry allows you to create workspaces for each of your deployment phases. You can then store artifacts in each workspace that are destined for that phase’s deployment environment.

Improved Interoperability

Two of the service registry’s pre-bundled policies can help improve your web service interoperability: WS-I BasicProfile compliance and WSDL backward compatibility. The WS-I BasicProfile compliance policy is a standard that outlines best practices to ensure your web service is interoperable. The service registry can ensure that your WSDLs meet these requirements. The WSDL backward compatibility policy ensures that your WSDL service operations are backward compatible with previous versions of your WSDL.

Simplified Mule Application Deployment

Typical pitfalls of application deployments are inconsistent processes, ad hoc changes to configuration during deployment, and lack of ability to roll back to the previous deployment. With the service registry and Mule NetBoot, you can create an application deployment strategy that is consistent, tracks all changes, and makes upgrades and rollbacks easier. The service registry becomes the runtime repository for your applications, and Mule NetBoot acts as the runtime container that loads your Mule application.

Collaboration

Unlike many commercial registries, the service registry for Mule ESB Enterprise deals with more than WSDL contracts. Typical SOA or EAI projects require a range of artifacts that make up your services, including XSLT transformations, annotated classes, XML message schema, or OSGi bundles. The service registry can become the single source of truth for all of your project artifacts. Members of the project can have access to these artifacts with associated lifecycle and metadata.

This approach becomes very powerful when design-time policies are applied to artifacts to ensure that they conform to the polices of the project before they can be submitted. For example, a common problem in outsourced code development is the time spent ensuring

Service Registry Features Chapter 1 Introduction to the Service Registry


that the artifacts created by the remote team conform to the larger project’s policies. The service registry greatly reduces this effort by enforcing policies as the artifact is submitted to the service registry instead of having to evaluate the artifacts later.

The Service Registry in Your Workflow

The service registry can fit easily into your existing development workflow. Following is a breakdown of how it fits into the four stages.

In stage one, your developers create services. The development build containing those services is published to the service registry, typically through a continuous integration server.

In stage two, your policy managers verify those services against SLAs and then promote the services to the Staging phase. This can trigger automated tests and scripts that run validation on the code. The services can then be promoted to the Production phase.

In stage three, your IT/operations group can track service dependencies and use Mule NetBoot to load applications that require the services.

In stage four, your consumers browse the published services and documentation. They can add comments and register to be notified of changes. You can also provide links to an issue-tracking system so that they can file issues against specific artifacts.

Service Registry FeaturesThis section describes the features in the service registry for Mule ESB Enterprise.

Artifact Management and Organization

The service registry provides an array of artifact-management capabilities based on workspaces, which organize configurations, policies, schemas, or any other artifacts your application needs. The workspace design provides a flexible mechanism to manage your artifacts.


Chapter 1 Introduction to the Service Registry Service Registry Features

Easy Access to Important Artifact Details

The service registry stores and displays artifact details such as name, description, lifecycle phase, and version. Metadata is extracted from artifacts or supplied by the user. The service registry includes built-in capabilities to recognize many different types of artifacts and can build the metadata automatically through indexes.

For example, if you add a Mule configuration to the service registry, it extracts the names of the Mule services, models, custom transformers, and other relevant details. You can easily view this information about the artifact and search by querying a specific property. In addition to Mule configurations, you can store WSDL documents, XML schemas, WS-Policy documents, and Spring configurations.

Metadata

While the service registry can automatically index artifacts for you, you can also supply your own metadata. You can easily define new properties, such as the group developing the artifact or the cluster for which the artifact is destined.

Searching

The service registry provides a set of sophisticated search capabilities. The structured search on the workspaces page allows you to query an artifact based on its name, description, and lifecycle phase. You can also search based on the metadata associated with the document, whether this is generated from an index such as the WSDL Services index or a user-defined property. The service registry also supports a SQL-like syntax for search.

Lifecycle Management

Artifacts progress through lifecycle phases inside the service registry. This helps users and administrators make informed judgments about the state of the artifact and manage each stage of its lifecycle. For example, a QA team can look for artifacts inside the repository that are in the Developed phase, perform the necessary testing on them, and migrate them to the Tested phase.



Dependency Management

The service registry can automatically detect artifact dependencies. If you have a WSDL or schema that contains imports, the service registry finds them and links the artifacts together. Users and administrators can easily see who else is consuming your services and plan for how changes to a service will affect others.

Policy Enforcement

The service registry allows you to implement governance rules across your organization. Policies can be applied globally or at the workspace level to artifact lifecycles. The service registry includes several built-in policies that can perform the following:

Enforce WS-I BasicProfile compliance Require Mule configurations to only use SSL-encrypted HTTP Enforce WSDL backward/forward compatibility

Because the service registry is based on the open-source Galaxy project, you can also create your own policies that are unique to your organization.

Application Deployment Management (Mule NetBoot)

Mule NetBoot can load applications remotely from the repository, making the service registry the central source of truth as to which applications and versions are deployed. To upgrade or roll back to a previous version of an application or Mule distribution, you simply update the application in the repository, and NetBoot dynamically loads both the application and the Mule distribution over the network.

Extensibility

The service registry is highly customizable, allowing power users to write custom extensions that can run periodically to perform tasks such as:

Listening for lifecycle transition events and sending automated alerts Pruning old builds from a development instance Installing new custom policies


Chapter 1 Introduction to the Service Registry Service Registry Features

Activity Monitoring

An important aspect of governance is the logging of all relevant changes inside the registry. Activities such as lifecycle transitions, the addition of new artifacts, or the changing of metadata are all logged inside the service registry. Changes and updates are easily viewable and searchable from the Activity tab, allowing you to track the changes that were made.

Additionally, these important activities can trigger an internal event, resulting in actions such as sending notifications or applying remote policies

Indexes

The service registry can index your artifacts using XPath or XQuery and includes several indexes for Mule configurations, WSDLs, XML schemas, and Spring configurations. You can also create your own custom indexes. Through simple XPath or XQuery expressions, you can extract useful information out of your artifacts for searching and viewing later.

Atom Publishing Protocol API

The service registry exposes its artifacts and workspaces through the RESTful Atom Publishing Protocol (APP). APP is a simple HTTP protocol for querying collections, accessing resources, and modifying them. Because APP is just HTTP, it is extremely simple to integrate the service registry with a large number of applications.

Integration with Mule, CXF, and Spring

Governance requires integration with service components. Service registry plug-ins for Mule, Apache CXF, and Spring provide immediate results:

Load and manage Mule ESB configurations Search sets of policies and apply them to Apache CXF services Pull sets of bean definitions through a Spring application context

Because the service registry is based on the open-source Galaxy project, you can create your own integration plug-ins unique to your organization.



Federation Capabilities

The service registry for Mule ESB Enterprise includes exclusive features enabling basic federation capabilities involving multiple instances of the service registry:

Remote Workspaces: attach remote workspaces to a local instance of the service registry, allowing users to browse other service registry instances.

Replication: easily copy workspaces from one service registry instance to another, enabling additional lifecycle management capabilities, such as pushing production-worthy artifacts/entries from a development instance of the service registry to a production instance.

These features are not available in the open-source Galaxy project.

Other Exclusive Features in the Service Registry

The service registry for Mule ESB Enterprise includes a number of additional features geared towards mission-critical enterprise deployments, including:

Clustering for high availability and fault tolerance

Extensible query engine for searching custom artifact types

MS Office search support

These features are not available in the open-source Galaxy project.


Chapter 1 Introduction to the Service Registry Service Registry Architecture

Service Registry ArchitectureThe following diagram illustrates how the service registry’s features work together:

Additional ResourcesThe following resources provide more information on the service registry and governance.

Dan Diephouse’s Blog (Lead developer of Galaxy): http://netzooid.com/blog

Using Galaxy to Discover Schemas: http://netzooid.com/blog/2008/02/12/using-galaxy-to-discover-schemas/

You Can’t Buy Governance by Anne Thomas Manes: http://akamai.infoworld.com/event/soa/07/november/docs/You_Cant.pdf

http://netzooid.com/blog

http://netzooid.com/blog/2008/02/12/using-galaxy-to-discover-schemas/

http://akamai.infoworld.com/event/soa/07/november/docs/You_Cant.pdf

Additional Resources Chapter 1 Introduction to the Service Registry



Chapter 2

Getting Started

This chapter describes how to get started with the service registry for Mule ESB Enterprise. It contains the following sections:

“Prerequisites” on page 19 “Downloading the Service Registry” on page 20 “Running the Standalone Service Registry” on page 20 “Configuring the Service Registry WAR” on page 21 “Logging Into the Service Registry” on page 23 “Frequently Asked Questions” on page 23

PrerequisitesEnsure that you have met all the prerequisites in this section before you download the service registry.

Java

The service registry requires you to have Java 5 or later installed. For validation of WSDLs to work correctly (part of the WS-I BasicProfile), you must have Java 6 (version 1.6.0_10 or later) installed, or endorse Xerces by adding the following libraries to your $JAVA_HOME/jre/lib/endorsed directory:

http://repo1.maven.org/maven2/xerces/xercesImpl/2.8.1/xercesImpl-2.8.1.jar http://repo1.maven.org/maven2/xml-apis/xml-apis/1.3.04/xml-apis-1.3.04.jar http://repo1.maven.org/maven2/xalan/xalan/2.7.0/xalan-2.7.0.jar

If you use Java 5 and do not endorse these JARs, you will get an error message warning you that schema validation does not work correctly. This is because of a bug in Java 5.

http://repo1.maven.org/maven2/xerces/xercesImpl/2.8.1/xercesImpl-2.8.1.jar

http://repo1.maven.org/maven2/xml-apis/xml-apis/1.3.04/xml-apis-1.3.04.jar

http://repo1.maven.org/maven2/xalan/xalan/2.7.0/xalan-2.7.0.jar

Downloading the Service Registry Chapter 2 Getting Started


Environment Settings

You must have at least 128MB of heap memory available to your JVM. If you are running MacOS X, you might need even more. If you will be running the service registry as a standalone application, you can add the -Xmx128m switch to the java command when you launch the service registry. If you will runthe service registry in a servlet container, see your container’s documentation.

Additionally, Linux and UNIX users might need to increase the maximum number of open file handles in the system to 2048 or higher. Otherwise, JAR indexing could fail under load (such as when uploading Mule via Mule NetBoot). For instructions, see http://www.cyberciti.biz/faq/linux-increase-the-maximum-number-of-open-files.

Downloading the Service RegistryTo download the service registry for Mule ESB Enterprise, go to http://mulesupport.mulesource.com/portal/secure/app/download.mule (you must log in to the MuleSource customer portal to access this page) and click the link for the JAR or WAR, depending on whether you want to run the service registry as a standalone application or embedded within a servlet container. Save the file to the directory where you want to run the service registry (for example, you might create the folder C:\MuleServiceReg).

To run the service registry as a standalone application, see the next section. To run the service registry WAR in a servlet container, configure it using the configuration utility (see “Configuring the Service Registry WAR” on page 21), and then deploy it to your servlet container as described in your container’s documentation.

Running the Standalone Service RegistryAfter you have downloaded the standalone service registry JAR, type the following string in a command window:

java -Xmx128m -jar galaxy-ee-web-standalone-<version>.jar

where <version> is the version number of the file. This will start the service registry on http://localhost:8080.

http://www.cyberciti.biz/faq/linux-increase-the-maximum-number-of-open-files

http://mulesupport.mulesource.com/portal/secure/app/download.mule


Chapter 2 Getting Started Configuring the Service Registry WAR

To specify a different port, use the httpPort argument:

java -Xmx128m -jar galaxy-ee-web-standalone-<version>.jar --port 9090

Warning Always leave the command window open while the service registry is running.

To stop the service registry, enter Ctrl-C in the command window before you close it. If you do not stop the service registry properly before you close the command window, the process will still run in the background. If you then try to run the service registry again, it will create a new instance that will conflict with the running instance, and the service registry will not start. If you accidentally close the command window without stopping the service registry first, you must shut down the Java process manually.

When you see the message INFO: Started [email protected]:8080, you are ready to log in to the service registry as described in “Logging Into the Service Registry” on page 23.

Configuring the Service Registry WARIf you will be running the service registry in a servlet container, you can use the configuration utility to configure the following deployment options:

Backend Database. By default, the service registry uses an embedded Derby instance that requires no further configuration. You can configure the service registry to use MySQL, PostgreSQL, Derby (embedded), or another database (Other). You can roll back to the default Derby configuration if needed.

Note that the embedded Derby architecture doesn’t support clustering. To use clustering, use an external database instance instead. You can use the Other option to configure other databases that have not been tested with the service registry, such as Oracle or MSSQL.

Custom Settings. You can create custom settings when no pre-configured option is available.

Service Registry Cluster. If you need high availability/failover, you can deploy the service registryin a cluster so that multiple instances of it can access the same artfiacts, entries, and metadata. The back end is a shared database, the JCR repository runs in a journal clustered mode, and the webapp is clustered via the standard Java EE means for webapps, ideally fronted with a load balancer. Every node in the cluster is active and shares state, so a request can be processed by any node. Using the configuration utility, you then set the following options for clustering:

Configuring the Service Registry WAR Chapter 2 Getting Started


Node identification for each WAR deployed. This is a unique identifier within a service registry cluster.

Whether BLOBs should be stored inside or outside the database instance. Many databases can’t stream large BLOBs properly and must store them outside of the database.

Shared storage location for BLOBs. Typically, this is an NFS mount or otherwise network-accessible area. This setting applies only if a cluster is being configured.

Prerequisites

Before you can configure the service registry WAR, you must:

Have a Java runtime available. Download the service registry configuration utility from


Using the Configuration Utility

After downloading the configuration utility, you launch it by running the following command at the command line and then following the on-screen prompts:

java -jar galaxy-config-dist-<version>.jar -s <path-to-galaxy.war> -d <path-to-dest-galaxy.war>

where <version> is the version number of the file, <path-to-galaxy.war> is the full path to the galaxy.war file, and <path-to-dest-galaxy.war> is the full path to the WAR file you are creating. For example:

java -jar galaxy-config-dist-1.5.2.jar -s C:\MuleServiceReg\galaxy.war -d C:\MuleServiceReg\galaxy1.war

You use the -d switch to write the modified deployment unit to a new file (specify the full path and file name). If you want to just update the existing service registry WAR file, you can omit the -d switch. A full list of options is available via the --help switch.

After the WAR is processed, it is ready for deployment.



Chapter 2 Getting Started Logging Into the Service Registry

Logging Into the Service RegistryTo log into the service registry, point your web browser to http://localhost:8080 (your URL may be slightly different if you’ve embedded service registry in your servlet container or you’ve used a non-default port). The initial user name and password are admin.

You are now ready to start using the service registry as described in the next chapter.

Frequently Asked QuestionsFollowing are some frequently asked questions about the service registry.

How do I upload groups of artifacts?

You can use a simple bash script to upload groups of artifacts using the curl command. Following is an example that uploads all the XML schemas in a directory:

#!/bin/shfor file in *.xsd; do curl -v -d @$file -u admin:admin -H "Content-Type: application/octet-stream" \ -H "X-Artifact-Version: 1.0" -H "Slug: $file" http://localhost:8080/api/registry/Default%20Workspace

done

Why do I get ClassNotFoundException on startup complaining about the JDBC driver?

The JDBC driver is not included with the service registry. Consult your servlet container documentation on the location where you should deploy one.

Can I use the configuration utility to switch backends for existing service registry instances?

The configuration utility is intended for initial setup. Contact MuleSource support for assistance migrating existing instances.

Frequently Asked Questions Chapter 2 Getting Started


Why do I get OutOfMemoryError when uploading big files?

If there was a custom configuration, ensure that externalBLOBs was enabled. In most cases, this error occurs if your database driver does not stream BLOBs.

I received an “Invocation of init method failed” error

This error occurs when there is a conflict with the JAXB libraries bundled with the service registry and the JAXB libraries that are included in Java 6. This happens only in older versions of Java 6. If you update to Java 1.6.0_10, the service registry runs without the startup errors.

Does the service registry support UDDI?

No. The service registry uses a RESTful AtomPub API instead of using UDDI to maximize ease of use and functionality. This HTTP interface provides a simple way to query, retrieve, and update items in the registry/repository, as well as to add integration for new applications, using your favorite HTTP client.


Chapter 3

Using the Service Registry

This chapter describes the basic usage of the service registry. It contains the following sections:

“Viewing the Repository Contents” on page 25 “Managing Workspaces” on page 26 “Managing Artifacts and Entries” on page 28 “Searching Artifacts and Entries” on page 32 “Editing Multiple Objects” on page 33 “Subscribing to Change Notifications” on page 34

Viewing the Repository ContentsWhen you first log in, the Registry tab appears. This tab allows you to look at various workspaces, select artifacts to view, search the registry, and manage workspaces.

Managing Workspaces Chapter 3 Using the Service Registry


You can filter the display by clicking the types of artifacts you want to see under Display. The list of artifacts is limited to the types you selected. To clear the filter and see all types again, click the refresh icon next to Display. You can also limit the display to specific workspaces by clicking the workspace in the list at the top of the screen.

To filter the display based on more advanced search criteria, such as all artifacts with a specific string in their name, see “Searching Artifacts and Entries” on page 32.

The rest of this chapter describes working with the controls on the Registry tab.

Managing WorkspacesThe service registry for Mule ESB Enterprise provides an array of registry/repository capabilities, using a workspace to organize services, configurations, policies, schemas, and any other artifacts your application needs. Workspaces are simply folders that hold services, artifacts, and other workspaces inside of them. For example, you might want to create a workspace for specific applications, groups of services, or global policies.

Using Workspaces

The service registry includes one default workspace. You can create new workspaces by clicking the Add Workspace link. You can edit an existing workspace by clicking the edit icon next to the folder icon. You can replicate workspaces by creating a script—for more information, see “Replicating Workspaces” on page 74.

Users with administrative privileges can attach workspaces in a remote instance of the service registry to a local workspace. For more information, see “Creating Remote Workspaces” on page 64.


Chapter 3 Using the Service Registry Managing Workspaces

Applying Policy Enforcement

The service registry allows you to implement governance rules across your organization. Policies can be applied globally or at the workspace level. The service registry includes several built-in policies. The following table describes these policies and where to find more information. Note that pages in the Mule User Guide require you to log in.

Policy Description

Mule: Require JMX Policy In Mule configuration files, requires that JMX monitoring is enabled. For more information, see the JMX Management page in the Mule User Guide at http://www.mulesource.org/x/XwKV.

Mule: Require No Client Remoting Policy

In Mule configuration files, requires that remote dispatcher support for the Mule client is not enabled. For more information, see the Mule Client page in the Mule User Guide at http://www.mulesource.org/x/34DR.

Mule: Require Non-local Endpoints Policy

In Mule configuration files, requires that all endpoints must be defined as global (top-level) endpoints instead of being defined as individual endpoints. For more information, see Configuring Endpoints in the Mule User Guide at http://www.mulesource.org/x/TQKV.

Mule: Require SSL Policy In Mule configuration files, requires that all HTTP and TCP endpoints be SSL-enabled.

WSDL: Backward Compatibility For WSDL documents, requires that all new versions are backward compatible with previous WSDL versions.

WSDL: WS-I BasicProfile 1.1. Compliance

For WSDL documents, requires that they meet the criteria outlined by the WS-I BasicProfile.

http://www.mulesource.org/x/XwKV

http://www.mulesource.org/x/34DR

http://www.mulesource.org/x/TQKV

Managing Artifacts and Entries Chapter 3 Using the Service Registry


If you have administrative privileges, you can edit the currently enforced policies at the global level (see “Managing Policies” on page 63). To edit the currently enforced policies at the workspace level, click a workspace on the Registry tab, click Manage Workspace, and then click Governance. Select a lifecycle, select a lifecycle phase or all phases, and then enable policies on it.

To enable a policy, select a policy in the left column and click > to move it to the right column.

Managing Artifacts and EntriesThe service registry contains two classes of items that can be stored in the repository: artifacts and entries. Artifacts are versioned files that are stored, such as Mule configurations, WSDLs, and schemas. Artifacts can also contain various types of metadata that you attach to them. Entries provide information about services. For example, you could create an entry to represent a service in your application and attach metadata such as where to find documentation, a URL to access it, or the business group.


Chapter 3 Using the Service Registry Managing Artifacts and Entries

Types of Artifacts

At the core of the service registry is an artifact repository, which can store any type of file. It has built-in support for recognizing a number of artifact types, including:

Mule configurations Spring configurations XSLT stylesheets XML schemas WSDL documents WS-Policy documents

If you have administrator privileges, you can add support for new artifact types and modify existing artifact types. For more information, see “Managing Artifact Types” on page 56.

Viewing Artifact and Entry Details

To view information about an artifact or entry, click its name on the main page.

The Info tab displays several pieces of information, including name, description, metadata, and comments. If you are viewing the details of an artifact, it also displays the media type, XML document type (if it is an XML document), lifecycle phase, and any dependencies. You

Managing Artifacts and Entries Chapter 3 Using the Service Registry


can also click the History tab to see the version history, and click the Security tab to see information about which user groups can read, modify, and delete this artifact or entry. To view the artifact itself, click the View Artifact link at the top of the screen.

Working with Metadata

You can manually create metadata for artifacts and entries by adding a metadata property. There are two types of metadata: global metadata and versioned metadata. Global metadata does not change between versions of the artifact, whereas versioned metadata can change from version to version. To specify a property, click the Add link in the Metadata or Versioned Metadata section, depending on whether you want this property to be global or versioned, select the property, and then specify a value for it. If you need to create a new property type and you have administrative privileges, see “Managing Properties” on page 62.

The service registry also uses indexes to extract metadata automatically from artifacts, making it easy to search. For more information, see “Searching Artifacts and Entries” on page 32. If you have administrative privileges, you can manage how these indexes work. For more information, see “Managing Indexes” on page 57.

Managing Lifecycles

Artifacts progress through lifecycle phases inside the service registry. This helps users and administrators make informed judgments about the state of the artifact and manage each stage of its lifecycle. For example, a QA team can look for artifacts inside the repository that are in the Developed phase, perform the necessary testing on them, and migrate them to the Tested phase.

There is one default lifecycle in the service registry. The phases occur in this order:

1 Created

2 Developed

3 Tested

4 Staged

5 Deployed

6 Retired


Chapter 3 Using the Service Registry Managing Artifacts and Entries

Each artifact starts out in the Created phase. You can move an artifact to a new phase by clicking the edit icon while viewing an artifact, selecting a new lifecycle phase, and then clicking Save.

If you have administrator privileges, you can modify the lifecycles, including deleting existing lifecycles, creating new lifecycles, and adding and deleting phases. For more information, see “Managing Lifecycles” on page 62.

Managing Dependencies

The service registry can automatically detect artifact dependencies. If you have a WSDL or schema that contains imports, the service registry will find the imports and link the artifacts together inside the service registry. This allows users and administrators to easily see who else is consuming your services and plan for how changes will affect them.

You can view dependencies when viewing an artifact. A dependency displays which artifacts it depends on and which artifacts depend on it.

You can manually create a dependency on another artifact in the repository by clicking the Add link in the Metadata or Versioned Metadata section (depending on whether you want the dependency to be applied globally to this artifact or make it specific to each version) and

Searching Artifacts and Entries Chapter 3 Using the Service Registry


selecting Depends On from the drop-down list. You can start typing the name of the artifact on which this artifact depends, and the list will display matching artifacts. After selecting the artifact, click Add, and then click Save.

Searching Artifacts and EntriesThe service registry provides a set of sophisticated search capabilities. The structured search on the workspaces page allows you to query an artifact or entry based on its name, description, and lifecycle phase. You can also search based on the metadata associated with the document.

To search, go to the Search tab. You can then select various fields and the values that you’re searching for. To search for an exact value, select has value. To enter part of the search term, such as part of the artifact or entry’s name, select has value like. To exclude items with a specific search term, choose doesn’t have value. To add another search term, click the + button. To remove a search term, click its - button.

The service registry also supports a SQL-like syntax for search via the Galaxy Query Language (GQL). To enter a GQL search, click Use Freeform Query and enter the string. For more information, see Appendix A, “Galaxy Query Language.”

When displaying the freeform query, you can display the search fields again by clicking Use Structured Query.

Saving Searches as Views

Views allow you to save a filtered set of objects, or view, in the registry for quick retrieval later.


Chapter 3 Using the Service Registry Editing Multiple Objects

To create a view:

1 On the Registry tab, click New next to View in the left-hand pane.

2 Enter a unique name for this view, and specify whether you want to share this view with other users who log in to this instance of the service registry.

3 In the Workspace text box, type the name of the workspace containing the objects you want to view. To includes workspaces contained within this workspace, click Include Child Workspaces.

4 Specify the search criteria as described above.

5 Click Test if you want to preview the results. Click Clear if you want to clear the results and start over.

6 Click Save.

To edit or delete a view:

1 On the Registry tab, select a view from the View list, and then click the Edit link next to the view’s name.

2 If you want to delete the view, click Delete.

3 To edit the view, modify its settings and criteria, and then click Save.

Editing Multiple ObjectsThe Bulk Edit link on the Registry tab allows you to edit multiple artifacts and/or entries simultaneously. For example, you could change the lifecycle phase for all your Mule 2 Configuration files at once.

If you have a large number of objects in your registry, a good practice is to filter the display before you bulk edit so that just the objects you want to edit appear on the screen. You can do this by clicking the display types on the left, by selecting a saved view (see “Saving Searches as Views” on page 32), or by starting a new search (see “Searching Artifacts and Entries” on page 32). If you don’t have that many objects, you can simply click Bulk Edit, select the objects you want to edit, and then click Edit Selected.

Subscribing to Change Notifications Chapter 3 Using the Service Registry


To bulk edit:

1 On the Registry tab, click Bulk Edit.

2 If you have already filtered the objects, click Edit All. Otherwise, click the check box of the objects you want to edit, and then click Edit Selected.

3 To add a setting, click Set, select the property you’re setting, and then specify the value for the property.

4 To remove a setting, click Remove, and then select the property you’re removing.

5 Specify whether this change applies to the global metadata section of the artifact (Apply to Artifact/Entry), to the versioned metadata in the latest version, or to the versioned metadata in all versions.

6 Click Save.

Subscribing to Change NotificationsThe service registry provides an RSS feed of changes to its repository. You can subscribe to this feed to be notified about changes to a specific artifact/entry or an entire workspace.

To subscribe to the workspace feed, select the workspace on the Registry tab, click Feed, and then specify the options provided by your browser for subscribing to this feed.

To subscribe to notifications on a specific artifact, select the artifact or entry on the Registry tab, and then click Version Feed if you want to subscribe to changes to the artifact/entry version or click the Atom feed icon next to Comments to subscribe just to new comments.


Chapter 4

Integrating Applications

This chapter describes how to integrate your existing applications with the service registry for Mule ESB Enterprise so that you can manage their artifacts. It contains the following sections: “Introduction” on page 35 “Installing the Plug-ins” on page 36 “Mule 2.x Integration” on page 36 “Mule 1.x Integration” on page 39 “Apache CXF Integration” on page 41 “Spring Integration” on page 43 “Publishing a Maven Project to the Service Registry” on page 43

IntroductionYou can integrate any number of applications with the service registry so that you can manage them and their artifacts simultaneously. The service registry provides default plug-ins for several applications, so you can integrate those applications with the service registry right away. The service registry also exposes an API via HTTP and the Atom Publishing Protocol API that you can use to write plug-ins for additional applications. For more information, see http://mulesource.org/display/GALAXY/HTTP+AtomPub+API.

Typically, plug-ins query the service registry using the Galaxy Query Language (see Appendix A, “Galaxy Query Language”) and receive a collection of Atom entries back in the response. Each Atom entry has a link to an artifact that was found in the query. The plug-in can then load each artifact and process it appropriately.

http://mulesource.org/display/GALAXY/HTTP+AtomPub+API

Installing the Plug-ins Chapter 4 Integrating Applications


Installing the Plug-insThe plug-ins are contained in the file galaxy-integration-distribution-version.zip. For example, you can download the 1.5.2 version from: http://repository.muleforge.org/org/mule/galaxy/galaxy-integration-distribution/1.5.2/galaxy-integration-distribution-1.5.2.zip.

To use a plug-in, set up your application as you would without the service registry. Then, drop the libraries from the distribution onto your classpath. Finally, follow the instructions for the plug-in as described in the following sections:

Mule 2.x IntegrationThe service registry can manage Mule 2.x XML configuration files as well as enforce polices on Mule configuration documents. It also allows you to start Mule from configuration files stored in the service registry by using org.mule.galaxy.mule2.config.GalaxyConfigurationBuilder. For information on Mule NetBoot, which allows you to start Mule on multiple remote computers from a single Mule instance in the service registry, see Chapter 7, “Using Mule NetBoot.”

Plug-in Description See:

Mule 2.x Allows you to start Mule 2.x instances with a simple URL that loads Mule configurations from the service registry, either from the command line or the API.

page 36

Mule 1.x Supports Mule 1.x instances. page 39

Apache CXF Selects policies based on a query, then applies them to services and clients. This plug-in allows you to easily manage and create global policies.

page 41

Spring Loads Spring beans into a GalaxyApplicationContext based on a query.

page 43

Maven Publishes your Maven project to the service registry. page 43

http://repository.muleforge.org/org/mule/galaxy/galaxy-integration-distribution/1.5.2/galaxy-integration-distribution-1.5.2.zip

http://repository.muleforge.org/org/mule/galaxy/galaxy-integration-distribution/1.5.2/galaxy-integration-distribution-1.5.2.zip


Chapter 4 Integrating Applications Mule 2.x Integration

Starting Mule from Code

If you embed Mule in a Java class, and the Mule configuration files are in the service registry, you can use the following code to start a Mule instance. The search query uses the Galaxy Query Language to specify the search criteria used to obtain one or more artifacts (Mule configuration files), in this case specifying that the server ID is hello-server:

String serverURL = "http://admin:admin@localhost:9002/api/registry";String query = "?q=select artifact where mule2.server.id = 'hello-server'";GalaxyConfigurationBuilder builder = new GalaxyConfigurationBuilder(serverURL + query);MuleContext context = new DefaultMuleContextFactory().createMuleContext(builder);

Starting Mule from Scripts

If you launch Mule from startup scripts from the Mule distribution, and the Mule configuration files are in the service registry, you must take the following steps:

1 Add the service registry integration JARs to the /lib/user directory under your Mule home directory.

2 Add the -builder argument to the startup script (see below and change the -config argument to specify a configuration file that’s stored as an artifact in the service registry.

$MULE_HOME/bin/mule -builder org.mule.galaxy.mule2.config.GalaxyConfigurationBuilder -config http://admin:admin@localhost:9002/api/registry?q=select artifact where mule2.server.id = 'hello-server'

This command tells the Mule server to load the configuration from the service registry where the server ID is hello-server. You can pass in a property file to make the configuration URL less verbose, or pass the properties in as JRE system properties. For example, if you had a property file called galaxy.properties with the following contents:

galaxy.username=admingalaxy.password=admingalaxy.query=select artifact where mule2.service = 'GreeterUMO'

You could then pass in this property file using the following command:

$MULE_HOME/bin/mule -builder org.mule.galaxy.mule2.config.GalaxyConfigurationBuilder -props galaxy.properties -config http://localhost:9002/api/registry

Mule 2.x Integration Chapter 4 Integrating Applications


Mule 2.x Plug-in Configuration Reference

This section describes the properties, indexes, and policies associated with the Mule 2.x plug-in.

Properties

The following properties are associated with this plug-in:

Indexes

Following are the indexes in which Mule 2.x configurations can be queried from the service registry.

Policies

Policies allow for design time or runtime rules to be applied to artifacts in the registry. For more information on policies, see “Applying Policy Enforcement” on page 27.

Property Value

Content Type application/mule2+xml

Namespace mule (http://www.mulesource.org/schema/mule/core/2.1 or http://www.mulesource.org/schema/mule/core/2.1)

Display Name Type

Mule 2 Description xpath

Mule 2 Cluster Id xpath

Mule 2 Domain Id xpath

Mule 2 Services xquery

Mule 2 Global Endpoints xquery

Mule 2 Models xquery


Chapter 4 Integrating Applications Mule 1.x Integration

Mule 1.x IntegrationThe service registry can also manage the older Mule 1.x XML configuration files and enforce polices on them. It also allows you to start Mule from configuration files stored in the service registry by using org.mule.galaxy.mule1.config.GalaxyConfigurationBuilder. For information on Mule NetBoot, which allows you to start Mule on multiple remote computers from a single Mule instance in the service registry, see Chapter 7, “Using Mule NetBoot.”

Starting Mule from Code

If you embed Mule in a Java class, and the Mule configuration files are in the service registry, you can use the following code to start a Mule instance from a configuration in the service registry. The search query uses the Galaxy Query Language to specify the search criteria used to obtain one or more artifacts, in this case specifying that the server ID is hello-server:

String serverURL = "http://admin:admin@localhost:9002/api/registry";String query = "?q=select artifact where mule.server.id = 'hello-server'";GalaxyConfigurationBuilder builder = new GalaxyConfigurationBuilder();UMOManager manager = builder.configure(serverURL + query);

Starting Mule from Scripts

If you launch Mule from startup scripts from the Mule distribution, and the Mule configuration files are in the service registry, you must take the following steps:

1 Add the service registry integration JARs to the /lib/user directory under your Mule home directory.

2 Add the -builder argument to the startup script (see below and change the -config argument to specify a configuration file that’s stored as an artifact in the service registry.

$MULE_HOME/bin/mule -builder org.mule.galaxy.mule1.config.GalaxyConfigurationBuilder -config http://admin:admin@localhost:9002/api/registry?q=select artifact where mule.server.id = 'hello-server'

This command tells the Mule server to load the configuration from the service registry where the server ID is hello-server. You can pass in a property file to make the configuration URL less verbose, or pass the properties in as JRE system properties. For example, if you had a property file called galaxy.properties with the following contents:

Mule 1.x Integration Chapter 4 Integrating Applications


galaxy.username=admingalaxy.password=admingalaxy.query=select artifact where mule.descriptor = 'GreeterUMO'

You could then pass in this property file using the following command:

$MULE_HOME/bin/mule -builder org.mule.galaxy.mule1.config.GalaxyConfigurationBuilder -props galaxy.properties -config http://localhost:9002/api/registry

Mule 1.x Plug-in Configuration Reference

This section describes the properties, indexes, and policies associated with the Mule 1.x plug-in.

Properties

The following properties are associated with this plug-in:

Indexes

Following are the indexes in which Mule 1.x configurations can be queried from the service registry.

Property Value

Content Type application/mule2+xml

Namespace mule-configuration ()

Display Name Type

Mule Configuration Description xpath

Mule Server Id xpath

Mule Endpoints xquery

Mule Transformers xquery


Chapter 4 Integrating Applications Apache CXF Integration

Policies

Policies allow for design time or runtime rules to be applied to artifacts in the registry. For more information on policies, see “Applying Policy Enforcement” on page 27.

Apache CXF IntegrationThe the service registry plug-in for Apache CXF integration makes it possible to load sets of WS-Policy documents from the service registry and apply them to services. This can be done using the Apache CXF XML configuration or the CXF/Galaxy APIs.

The Apache CXF integration makes use of WS-Policy and Features inside CXF. You can learn more about these at http://cwiki.apache.org/CXF20DOC/wspconfiguration.html.

To use the service registry with CXF, you must use the supplied Galaxy Feature. This will take a series of query URLs and load the WS-Policy documents from the query results.

Integrating from the XML Configuration

To declare the Galaxy Feature inside your CXF XML, use the <galaxy> element:

<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:g="http://galaxy.mule.org/cxf/" xsi:schemaLocation="http://galaxy.mule.org/cxf/ http://galaxy.mule.org/schemas/cxf-galaxy.xsdhttp://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.0.xsd">

<g:galaxy id="galaxyFeature" username="admin" password="admin"> <g:policyQuery> http://localhost:9002/api/repository?q=select artifact from '/Policies/Global' where documentType = {http://www.w3.org/2006/07/ws-policy}Policy

Mule Models xquery

Mule Descriptors xquery

Display Name Type

http://cwiki.apache.org/CXF20DOC/wspconfiguration.html

Apache CXF Integration Chapter 4 Integrating Applications


</g:policyQuery> </g:galaxy>

...</beans>

This will select all WS-Policy documents from the workspace /Policies/Global. It will also enable the WS-Policy framework for you if it is not already enabled.

You must enable the Galaxy Feature on your service as follows:

<jaxws:service ....> <jaxws:features> <spring:ref bean="galaxyFeature"/> </jaxws:features></jaxws:service>

This will activate all policies that were found by the Galaxy Feature on your service.

Note Because of a bug in CXF, it is not currently possible to apply a set of policies globally (at the Bus level) with one declaration. Until this is resolved, you must reference the policy feature on each service.

Integrating from the API

It is easy to use the Galaxy Feature from the API as well. You start by creating your endpoint and casting it to the CXF EndpointImpl object:

EndpointImpl ep = (EndpointImpl) Endpoint.create(new org.apache.hello_world_soap_http.GreeterImpl());

Next, add the WS-Policy feature to the endpoint. In this case, we’re telling the engine we want to use the http://www.w3.org/2006/07/ws-policy version of WS-Policy.

WSPolicyFeature policyFeature = new WSPolicyFeature();policyFeature.setNamespace("http://www.w3.org/2006/07/ws-policy");ep.getFeatures().add(policyFeature);

Next, create the Galaxy Feature and add it to the service:

GalaxyFeature feature = new GalaxyFeature();feature.setUsername("admin");feature.setPassword("admin");


Chapter 4 Integrating Applications Spring Integration

String url = "http://localhost:9002/api/registry?q=" + org.apache.abdera.i18n.text.UrlEncoding.encode("select artifact from '/Policies/Global' where documentType = " + "{http://www.w3.org/2006/07/ws-policy}Policy");

feature.getPolicyQueries().add(url);ep.getFeatures().add(feature);

The URL that we create will select all WS-Policy documents from the /Policies/Global workspace.

Lastly, publish your service:

ep.publish("http://localhost:9003/greeter");

Spring IntegrationTo integrate Spring with the service registry, you simply pass a URL to the GalaxyApplicationContext in the constructor as follows:

String configURL = "http://admin:admin@localhost:9002/api/registry?q=select artifact where spring.bean = 'TestObject1'";

ApplicationContext context = new GalaxyApplicationContext(new URL(configURL));

.... = context.getBean("bean");

Publishing a Maven Project to the Service RegistryIf you create a Maven project, you can use the Galaxy Publishing plug-in for Maven to easily publish your project and/or its resources to the service registry repository. To use the plug-in, you add the service registry repository to your Maven POM, and then configure the plug-in using the <configuration> tags in your POM. You can also add useful links and configure security. The rest of this section describes these tasks.

Publishing a Maven Project to the Service Registry Chapter 4 Integrating Applications


Adding the Galaxy Repository to the POM

The first step is to add your service registry repository (or snapshot repository) to your Maven POM. The service registry repository includes the MuleForge repository, the Mule Dependencies repository, and the Apache Incubating repository:

<repositories> <repository> <id>muleforge</id> <url>http://repository.muleforge.org</url> <name>MuleForge Repository</name> </repository>

<repository> <id>mule.dependencies</id> <url>http://dist.codehaus.org/mule/dependencies/maven2/</url> <name>Mule Dependencies Repository</name> </repository>

 <repository> <id>apache-incubating</id> <name>Apache Incubating Repository</name> <url>http://people.apache.org/repo/m2-incubating-repository/</url> </repository></repositories>

Next, add the appropriate <dependency> entries.

<dependency> <groupId>org.mule.galaxy</groupId> <artifactId>galaxy-integration-cxf</artifactId> <version>1.0-beta-1</version></dependency>

<dependency> <groupId>org.mule.galaxy</groupId> <artifactId>galaxy-integration-mule1</artifactId> <version>1.0-beta-1</version></dependency>

<dependency> <groupId>org.mule.galaxy</groupId> <artifactId>galaxy-integration-spring</artifactId> <version>1.0-beta-1</version>


Chapter 4 Integrating Applications Publishing a Maven Project to the Service Registry

</dependency>

Configuring the Plug-in

After adding the service registry repository to the POM, you configure the plug-in as shown in the following example configuration, which publishes all the artifacts and their dependencies associated with the Maven project (with the exception of the Mule JARs, which are excluded) and all the XSD and WSDL files in src/main/resources:

<build><plugins><plugin>

<groupId>org.mule.galaxy</groupId> <artifactId>galaxy-maven-publish-plugin</artifactId> <version>1.0-RC</version> <configuration> <url>http://localhost:9002/api/registry/Default%20Workspace</url> <username>admin</username> <password>admin</password>

 <dependencyExcludes> <dependencyExclude>org.mule:mule-core</dependencyExclude> <dependencyExclude>org.mule.transports:*</dependencyExclude> </dependencyExcludes>  <includes> <include>src/main/resources/*.xsd</include> <include>src/main/resources/*.wsdl</include> </includes> </configuration> <executions> <execution> <id>publish-artifacts</id> <phase>package</phase> <goals> <goal>execute</goal> </goals> </execution> </executions>...

Publishing a Maven Project to the Service Registry Chapter 4 Integrating Applications


Configuring Useful Links

You can add URLs for your issue tracking, continuous integration, and source control management systems to the POM. These URLs will be extracted and attached as versioned metadata for each artifact published by Maven. Then, when a user views the artifact in the service registry and they want to file an issue or see the source code, for example, they can simply click the link right there in the artifact view.

The tags you use are <issueManagement>, <ciManagement>, and <scm>. For example:

<issueManagement> <system>jira</system> <url>http://www.yourcompany.org/jira/browse/YOURPROJECT</url></issueManagement>

<ciManagement> <system>bamboo</system> <url>http://bamboo.yourcompany.org/</url></ciManagement>

<scm><connection>scm:svn:http://svn.codehaus.org/myProject/branches/myApp-1.0</connection><developerConnection>

scm:svn:https://svn.codehaus.org/myProject/branches/myApp-1.0</developerConnection><url>http://svn.myProject.codehaus.org</url>

</scm>

For more information on using these tags, see the POM reference on the Apache site at http://maven.apache.org/pom.html.

Configuring Security Information

If you do not want to include the user name and password in your POM, you can put it in your ~/.m2/settings.xml file. The file will look like this:

<settings> <servers> <server> <id>myServer</id> <username>admin</username> <password>admin</password>

http://maven.apache.org/pom.html


Chapter 4 Integrating Applications Publishing a Maven Project to the Service Registry

</server> </servers></settings>

Then, you just need to specify a server ID in your plug-in configuration:

<configuration> ... <serverId>myServer</serverId> ...</configuration>

Additional Configuration Options

For more options you can use in the <configuration> section of the POM to configure the plug-in, see http://galaxy.muleforge.org/galaxy-maven-publish-plugin/execute-mojo.html

http://galaxy.muleforge.org/galaxy-maven-publish-plugin/execute-mojo.html


Chapter 5

Administering the Service Registry

Users with administrator privileges can add users and groups, manage lifecycles, and more. This chapter describes administration of the service registry. It contains the following sections:

“Managing Users and Groups” on page 48 “Managing Artifact Types” on page 56 “Managing Indexes” on page 57 “Managing Properties” on page 62 “Managing Lifecycles” on page 62 “Managing Policies” on page 63 “Creating Remote Workspaces” on page 64 “Monitoring Registry Activity” on page 65 “Installing Your Service Registry License” on page 66

Note The Administration tab includes utilities for creating scripts and running them as scheduled jobs. For more information, see Chapter 6, “Working with Scripts.”

Managing Users and GroupsThe service registry uses the common permissioning scheme of users and groups. Users are individuals who can log in to the service registry. Groups allow you to assign permissions collectively to a group of users, such as adding certain users to the Administrators group, which has permissions like Manage Users and Manage Properties assigned to it.

You manage users and groups on the Administration tab in the service registry. You can also use LDAP to enable authentication. The rest of this section describes these tasks:

“Managing Users” on page 49 “Managing Groups” on page 49 “Enabling Authentication Through LDAP” on page 51


Chapter 5 Administering the Service Registry Managing Users and Groups

Managing Users

This section describes how to create, edit, and delete a user in the service registry.

To create a user:

1 Click the Add link next to Users on the Administration tab.

2 Enter the user name that the user will enter when they log in to the service registry, as well as the user’s full name, email address, and password (at least five characters).

3 Select at least one group that you want this user to join.

The default groups are Administrators, and Users. If you need to create more groups, see “Managing Groups” on page 49.

4 Click Save.

To edit a user:

1 On the Administration tab, click Users, and then click the user name of the user you want to edit.

2 Edit the user’s name or email address if needed.

3 If you need to reset the user’s password, click Reset Password, enter the new password twice, and then click OK.

4 To add the user to a group, select it in the Available Groups list and click >. To remove a user from a group, select it in the Joined Groups list and click <.

5 When you have finished editing this user, click Save.

To delete a user:

1 On the Administration tab, click Users, and then click the user name of the user you want to delete.

2 Click Delete.

3 Click OK to confirm that you want to delete this user.

Managing Groups

This section describes how to add, edit, and delete a group in the service registry. Note that you cannot delete the Administrators group.

Managing Users and Groups Chapter 5 Administering the Service Registry


Available Permissions

Following are the permissions you can assign to groups when you create or edit them:

This permission... Allows users to...

Read Artifact/Entry View the details of an artifact or entry on the Registry tab

Modify Artifact/Entry Edit the details of an artifact or entry

Delete Artifact/Entry Delete an artifact or entry from the repository

Read Workspace View the contents of a workspace on the Registry tab

Modify Workspace Edit the contents of a workspace

Delete Workspace Delete a workspace

View Activity Log Display the Activity tab, which shows the activity log

Manage Users Display the Users link and view on the Administration tab, allowing users to add, edit, or delete users

Manage Indexes Display the Indexes link and view on the Administration tab, allowing users to add, edit, or delete indexes

Manage Groups Display the Groups link and view on the Administration tab, allowing users to add or delete groups or change a group’s permissions

Manage Policies Display the Policies link and view on the Administration tab, allowing users to change how policies are applied to lifecycle phases

Manage Properties Displays the Properties link and view on the Administration tab, allowing users to add, edit, or delete properties

Manage Lifecycles Displays the Lifecycles link and view on the Administration tab, allowing users to add, edit, or delete lifecycles

Manage Artifact Types Displays the Artifact Types link and view on the Administration tab, allowing users to add, edit, or delete artifact types

Execute Admin Scripts Displays the Admin Shell link and view on the Administration tab, allowing users to enter a Groovy script to be executed on the server.



To create a group:

1 Click the Add link next to Groups on the Administration tab.

2 Enter a name for this group and click Save.

The new group appears in the group list.

3 Assign the permissions you want users in this group to have (see “Available Permissions” on page 50).

4 When you have finished creating the groups you want, click Save.

5 To assign a user to this group, edit the user as described above.

To edit a group:

1 On the Administration tab, click Groups.

2 Edit the assigned permissions as needed (see “Available Permissions” on page 50).

3 If you want to change the group name, click the group name, type the new name, and then click Save.

Note You cannot edit the Administrators group.

4 When you have finished editing groups, click Save.

To delete a group:

1 On the Administration tab, click Groups, and then click the user name of the group you want to delete.

Note You cannot delete the Administrators group.

2 Click Delete.

3 Click OK to confirm that you want to delete this group.

Enabling Authentication Through LDAP

If you are using the WAR version of the service registry instead of the standalone version, the service registry can use an LDAP server to manage users and groups. To configure the service registry to use LDAP, you take the following steps:

Set up Service Registry Groups



Add the LDAP JAR to your classpath. Create the LDAP configuration file. Enable the configuration file

The rest of this section describes these steps in detail.

Set Up Service Registry Groups

In the service registry, you must create the same groups as those on the LDAP server and set the appropriate permission levels. For instance, if an administrator adds a group called Developers to the LDAP server, you must create that same group in the service registry and configure the appropriate permissions.

To create the groups in the service registry, do one of the following:

Create a group called Administrators on the LDAP server. The service registry comes with a set of default permissions for users in the Administrators group. Ensure that the user you want to use is in the Administrator group and log into the service registry. You can then create other groups, assign the appropriate permissions, and remove the original Administrators group from the LDAP server.

Start a service registry instance without LDAP enabled. Create groups in the service registry instance that correspond to your groups on the LDAP server (see page 49). Then, follow the instructions below to enable LDAP.

Add the LDAP JAR to your Classpath

The LDAP support JAR file contains the necessary classes for the service registry to authenticate against an LDAP server. Download the file http://repository.muleforge.org/org/mule/galaxy/galaxy-ldap/1.5.2/galaxy-ldap-1.5.2.jar to the service registry web application in the /WEB-INF/lib directory.

Create the LDAP Configuration File

You must create an LDAP configuration file called galaxy-ldap.xml and place it in /WEB-INF/classes. Following is an example template for this file, followed by a description of its properties:

<beans xmlns="http://www.springframework.org/schema/beans" xmlns:aop="http://www.springframework.org/schema/aop" xmlns:tx="http://www.springframework.org/schema/tx"

http://repository.muleforge.org/org/mule/galaxy/galaxy-ldap/1.5.2/galaxy-ldap-1.5.2.jar

http://repository.muleforge.org/org/mule/galaxy/galaxy-ldap/1.5.2/galaxy-ldap-1.5.2.jar



xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation=" http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-2.5.xsd http://www.springframework.org/schema/tx http://www.springframework.org/schema/tx/spring-tx-2.5.xsd http://www.springframework.org/schema/aop http://www.springframework.org/schema/aop/spring-aop-2.5.xsd"> <bean id="initialDirContextFactory" class="org.acegisecurity.ldap.DefaultInitialDirContextFactory"> <constructor-arg value="ldap://localhost:10389/"/> <property name="managerDn"><value>uid=admin,ou=system</value></property> <property name="managerPassword"><value>secret</value></property> </bean> <bean id="userSearch" class="org.acegisecurity.ldap.search.FilterBasedLdapUserSearch"> <constructor-arg value="ou=people"/> <constructor-arg value="(uid={0})"/> <constructor-arg ref="initialDirContextFactory" /> <property name="searchSubtree" value="true"/> </bean> <bean id="userDetailsMapper" class="org.mule.galaxy.security.ldap.UserLdapEntryMapper" /> <bean id="userManagerTarget" class="org.mule.galaxy.security.ldap.LdapUserManager" init-method="initialize"> <property name="initialDirContextFactory" ref="initialDirContextFactory"/> <property name="persisterManager" ref="persisterManager" /> <property name="userSearch" ref="userSearch"/> <property name="userMapper" ref="userDetailsMapper"/>  <property name="userSearchBase" value="ou=system"/> <property name="userSearchAttributes"> <map> <entry key="objectclass" value="person"/> </map> </property> </bean>



<bean id="ldapAuthProvider" class="org.mule.galaxy.security.ldap.GalaxyAuthenticationProvider"> <constructor-arg> <bean class="org.acegisecurity.providers.ldap.authenticator.BindAuthenticator"> <constructor-arg ref="initialDirContextFactory"/> <property name="userSearch" ref="userSearch"/> </bean> </constructor-arg> <constructor-arg> <bean class="org.mule.galaxy.security.ldap.LdapAuthoritiesPopulator"> <constructor-arg ref="initialDirContextFactory" /> <constructor-arg value="ou=groups,ou=system" /> <property name="groupSearchFilter" value="uniqueMember={0}"/> <property name="searchSubtree" value="true"/> <property name="rolePrefix" value=""/> <property name="convertToUpperCase" value="false"/> <property name="accessControlManager" ref="accessControlManager"/> </bean> </constructor-arg> <property name="accessControlManager" ref="accessControlManager"/> <property name="userMapper" ref="userDetailsMapper"/> </bean> <bean id="authenticationManager" class="org.acegisecurity.providers.ProviderManager"> <property name="providers"> <list> <ref bean="ldapAuthProvider"/> <ref bean="anonymousAuthenticationProvider"/> <ref bean="rememberMeAuthenticationProvider"/> </list> </property> </bean> </beans>

Following are the properties you set in this file:

The managerDn property of the initialDirContextFactory bean. This is the DN (distinguished name) of the user you will use to log in to the LDAP server.

The managerPassword property of the initialDirContextFactory bean. This is the password of the user you will use to log in to the LDAP server.



The first <constructor-arg> of the userSearch bean. This is the base context in which the service registry will search for users.

The second <constructor-arg> of the userSearch bean. This is a filter expression used to find entries that match a particular user name. For example, (uid={0}) would look for an entry where the uid attribute matches the user name.

The userSearchBase property of the userManager bean. This is the base context in which the service registry will search for users.

The userSearchAttributes property of the userManager bean. These attributes are used to search for users in the LDAP server.

The second <constructor-arg> of the LdapAuthoritiesPopulator bean. This is the DN of the context you will use to search for groups to which the user belongs.

The groupSearchFilter property of the LdapAuthoritiesPopulator bean. This is an expression that finds groups. For instance, (uniqueMember={0}) searches for groups inside of the groupSearchBase that have an attribute uniqueMember where one of the values is the user name.

Enable the Configuration File

Lastly, you enable the LDAP configuration file by adding a reference to it in the /WEB-INF/web.xml file in the service registry web application. In web.xml, navigate to the section that looks like this:

<context-param> <param-name>contextConfigLocation</param-name> <param-value> classpath:/META-INF/applicationContext-core.xml classpath:/META-INF/applicationContext-abdera.xml classpath:/META-INF/applicationContext-acegi-security.xml classpath:/META-INF/applicationContext-acegi-security-web.xml classpath:/META-INF/applicationContext-web.xml classpath:/META-INF/galaxy-applicationContext.xml </param-value> </context-param>

In the <param-value> element, add the new line shown in bold below:

<context-param> <param-name>contextConfigLocation</param-name> <param-value> classpath:/META-INF/applicationContext-core.xml

Managing Artifact Types Chapter 5 Administering the Service Registry


classpath:/META-INF/applicationContext-abdera.xml classpath:/META-INF/applicationContext-acegi-security.xml classpath:/META-INF/applicationContext-acegi-security-web.xml classpath:/META-INF/applicationContext-web.xml

classpath:/META-INF/galaxy-applicationContext.xmlclasspath:/galaxy-ldap.xml

</param-value> </context-param>

Managing Artifact TypesThe service registry can manage many different types of artifacts, including JAR files, Mule configuration files, WSDL documents, and much more. You can edit an artifact type to specify the document type and file extensions supported by that artifact type, or you can create a new artifact type.

To create an artifact type:

1 On the Administration tab, click Add next to Artifact Types.

2 In the Description field, enter a unique description for the artifact type as you want it to appear in the Artifact Types list.

3 In the Media Type field, enter the media type (MIME type or content type) of the files handled by this artifact type. For example, if this artifact type handles Acrobat files, enter application/pdf.

4 If this artifact type handles XML files, enter the qualified name of the file’s document type using the {NAMESPACE}LOCAL-NAME format, and then click Add.

For example, for XSTL you would enter {http://www.w3.org/1999/XSL/Transform}stylesheet. You can add multiple document types. If you make a mistake, select a document type and click Remove.

5 If this artifact type handles non-XML files, enter a file extension and click Add.

You can add multiple file extensions. If you make a mistake, select the file extension and click Remove.

6 Click Save.


Chapter 5 Administering the Service Registry Managing Indexes

To edit an artifact type:

1 On the Administration tab, click Artifact Types, and then click the name of the artifact type you want to edit.

2 Edit the settings as needed, and then click Save.

To delete an artifact type:

1 On the Administration tab, click Artifact Types, and then click the name of the artifact type you want to delete.

2 Click Delete, and then click OK to confirm that you want to delete the artifact type.

Managing IndexesIndexes create searchable properties for your artifacts. For example, if you add a Mule configuration to the service registry, indexes will create properties for the names of the services, model, custom transformers, and other relevant details, allowing you to quickly find the Mule configuration files you want by searching for specific values in those properties. For WSDL documents, the service registry can create properties for the service names, port types, and more. For more information on searching, see “Searching Artifacts and Entries” on page 32.

The service registry comes with several default indexes for Mule, WSDL, and Spring files. To view the current indexes, go to the Administration panel and click Indexes.

When you create an index, your index criteria can be written in either XPath or XQuery. The next sections describe these two types of indexes.

XPath Indexes

Let’s look at a simple index, the WSDL Target Namespace index. This index looks for the targetNamespace attribute on a WSDL document like this one:

<wsdl:definitions targetNamespace="http://mule.org/hello_world" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">...</wsdl:definitions>

Managing Indexes Chapter 5 Administering the Service Registry


If you click on the WSDL Target Namespace index, you’ll see the following screen:

This is an XPath index. It looks for values that match the XPath expression /*/@targetNamespace. This value will then become a property on any artifact where this expression returns results.

If you’re using GQL (see Appendix A, “Galaxy Query Language”), you specify the index ID as the property name inside your search statements. For example, you could use this query to return the previously mentioned document:

select artifact where wsdl.targetNamespace = 'http://mule.org/hello_world'

XQuery Indexes

While XPath indexes are powerful, XQuery allows you to create indexes that are much richer semantically and are able to extract more information from artifacts. In addition to just selecting XML nodes, you can select nodes conditionally, combine node values, and more.

The following example shows an index that extracts Spring bean IDs from a configuration file. In Spring configuration files, the id attribute and the name attribute on the <bean> element are semantically equivalent but are mutually exclusive. Therefore, it is common to have Spring files like this:



<spring> <bean id="foo" .../> <bean name="bar" .../></spring>

Following is an example of an XQuery expression that can index both of these properties simultaneously:

Looking at the XQuery statement, let’s break it down line by line:

declare default element namespace "http://www.springframework.org/schema/beans"

This declares the namespace http://www.springframework.org/schema/beans to be the default namespace in our search.

declare variable $document external

Managing Indexes Chapter 5 Administering the Service Registry


$document is the artifact XML document inside the service registry. This statement declares that this document will be provided to the XQuery expression via an external entity (the service registry).

<values> {

This is the beginning of our XML result set. We’re wrapping all the values we find.

for $e in $document//bean

Loop through each <spring:bean/> element.

return if ($e/@name) then <value>{data($e/@name)}</value> else <value>{data($e/@id)}</value>

If there is an @name attribute, return a <value> element with the name attribute inside it. Otherwise, return a <value> element with the id attribute inside it.

} </values>

The end of our XML result set.

All of this will return an XML result set like this:

<values> <value>foo</value> <value>bar</value></values>

Each value will then be set on the artifact and becomes searchable.

Working with Indexes

You can edit the default indexes that come with the service registry, or create new indexes.

To create an index:

1 Click Add next to Indexes on the Administration panel.

2 In the Description field, enter a unique description for this index as you want it to appear in the Indexes list.



3 If this index will apply to XML documents, and you want to index an element or type in the document (such as a dependency in a WSDL or a specific connector in a Mule configuration file), select QName from the Result Type list. In all other cases, leave String selected.

4 In the Media Type field, enter the media type (MIME type or content type) of the artifacts to which this index applies. For example, if this index will extract information from Acrobat files, enter application/pdf, for XSD documents enter application/xmlschema+xml, or for Mule configuration files enter application/mule+xml.

5 In the text field below the Document Types box, enter the qualified name using the {http://namespace}local-name format (for XML documents) or enter the file extension (for non-XML documents) of the artifacts you want this index to process, and then click Add.

For example, enter {http://www.w3.org/1999/XSL/Transform}stylesheet for XSLT stylesheets or enter pdf for Acrobat files. You can enter additional document types as needed. If you make a mistake, select a document type and click Remove.

6 Select whether you will specify the index criteria as an XPath expression (see page 57) or XQuery expression (see page 58).

7 In the Property Name text box, type a unique name for the property that this index is creating. You will use this property name in GQL queries.

8 Enter the expression that creates the property.

9 When you are finished creating the index, click Save.

To edit an existing index:

1 Click Indexes on the Administration panel, and then click the name of the index you want to edit.

2 Make the necessary edits, and then click Save.

To delete an index:

1 Click Indexes on the Administration panel, and then click the name of the index you want to delete.

2 Click Delete, and then click OK to confirm that you want to delete this index.

Managing Properties Chapter 5 Administering the Service Registry


Managing PropertiesWhile the service registry can automatically index artifacts and create searchable properties for you, you might also want to create your own properties manually. You can easily define new properties, such as the group developing the artifact or the cluster the artifact is destined for.

To add a property:

1 On the Administration tab, click the Add link next to Properties.

2 Enter a unique name for the property, which you can use to search for this property using the Galaxy Query Language (see Appendix A, “Galaxy Query Language.”)

3 Enter a description of the property, which appears in the drop-down list when you search this property using structured search.

4 Specify the property type: String, which allows you to specify text values; Lifecycle, which allows you to select a lifecycle to associate with the artifact; or User(s), which allows you to specify users to associate with the artifact.

5 If the type is a string, check the Multiple Values box if you want to be able to specify multiple values.

6 Click Save.

Managing LifecyclesA lifecycle is a series of phases that you can use to control artifacts managed by the service registry. For example, you can specify that one policy applies during the Developed phase and that another policy applies during the Production phase.

The service registry includes a default lifecycle with the phases Created, Developed, Production, Retired, Staged, and Tested. You can modify these phases and add new ones, or create a new lifecycle altogether with unique phases.

To create a new lifecycle:

1 On the Administration tab, click Add next to Lifecycles.

2 Enter a name for the lifecycle.

3 If you want this lifecycle to be used as the default, select the check box.


Chapter 5 Administering the Service Registry Managing Policies

4 Click Add to add the first phase in this lifecycle, enter a name for the phase, and then click OK.

The phase you just added appears on the right.

5 Click the Initial Phase check box to indicate that this is the first phase.

6 Click Add to add the next phase in the lifecycle.

7 After you have added the phases, click the first phase and highlight all the phases that will come after that phases in the list on the right. Repeat this step for each of the phases, highlighting the phases that will come after the phase.

8 When you have finished setting up the lifecycle, click Save.

To add a phase to an existing lifecycle:

1 On the Administration tab, click Lifecycles.

2 Click the name of the lifecycle to which you are adding phases.

3 Click Add, enter a name for the phase, and click OK.

4 In the list of phases on the right, highlight the phases that will come after this phase.

5 Click Save.

Managing PoliciesThe service registry comes with several predefined policies that you can use to control artifacts and entries during different phases in a lifecycle (see “Applying Policy Enforcement” on page 27). In addition to applying policies at the workspace level, you can apply them globally to specific lifecycle phases. If you want to create your own policies, see http://www.mulesource.org/display/GALAXY/Custom+Policies.

To globally apply or remove a policy from a lifecycle phase:

1 On the Administration tab, click Policies.

2 Select a lifecycle, and then select the phase to which you want to apply policies. If you want to apply a policy to all phases in the lifecycle, select All Phases.

3 Select the policies you want to apply to the selected phase, and then click >.

4 To remove a policy from a phase, select it from the right-hand list, and then click <.

http://www.mulesource.org/display/GALAXY/Custom+Policies

Creating Remote Workspaces Chapter 5 Administering the Service Registry


5 Click another phase to apply policies and repeat these steps.

6 When you have finished applying policies, click Save.

Creating Remote WorkspacesRemote workspaces are workspaces that exist in another service registry instance. The service registry allows you to attach these workspaces to your local instance so you can browse them and perform actions such as replication.

Note Searching across remote workspaces is not currently supported.

To attach a remote workspace:

1 On the Administration panel, click the Add link for remote workspaces.

2 Enter the information described below.

3 Click Save.

To delete a remote workspace attachment:

1 On the Administration panel, click Remote Workspaces.

2 Click the remote workspace path.

Field Description

Local Workspace Name The name that will appear locally for the remote workspace.

Attach to Workspace The local workspace in which you are attaching the remote workspace. As you type a name, local workspaces will be listed. To create a top-level workspace, leave this field blank.

URL The URL of the remote workspace’s Atom feed, using the format http://HOST/api/registry/PATH, where HOST is the remote service registry instance and PATH is the workspace, such as http://acme.com:8080/api/registry/Services/Accounting

Username The user name in the remote service registry instance that will be used to access the information.

Password The password for the above user.


Chapter 5 Administering the Service Registry Monitoring Registry Activity

3 Click Delete, and then click OK to confirm that you want to delete the remote workspace attachment.

Monitoring Registry ActivityAn important aspect of governance is the logging of all relevant changes inside the registry. Activities such as lifecycle transitions, the addition of new artifacts, or the changing of metadata are all logged inside the service registry. Changes and updates are easily viewable and searchable from the Activity tab, allowing you to track what changes were made.

You can filter the activity log by date, by the user who made the changes, and by artifacts or entries containing specific text or of certain types. You can also type the name of a specific artifact or entry in the Relating to box to see activity for just that item. Lastly, you can specify the maximum number of results you want to return. After specifying the filter conditions you want, click Search. To clear the filter and see all activity, click Reset.

Installing Your Service Registry License Chapter 5 Administering the Service Registry


Installing Your Service Registry LicenseWhen you install the service registry for Mule ESB Enterprise, you must install your license from MuleSource within thirty days. Otherwise, the trial version will expire.

To install the license:

1 If you have not yet obtained your license, contact MuleSource (see “MuleSource Technical Support” on page 8).

2 On the Administration tab, click Install License.

3 Browse to the location of your license file, and then click Submit.


Chapter 6

Working with Scripts

The Admin shell allows you to easily build and install your own extensions for the service registry. This chapter contains the following sections:

“Overview” on page 67 “Creating a Script” on page 67 “Modifying a Script” on page 68 “Scheduling a Script” on page 68 “Examples” on page 71

OverviewThe Admin shell allows you to easily build and install your own extensions for the service registry by writing scripts. You can then run the scripts on startup or schedule them using a cron-like scheduling mechanism. The scripts are written using the Java-like Groovy scripting language. For more information about Groovy, see http://groovy.codehaus.org/.

Creating a ScriptTo create a script, go to the Administration tab, click Admin Shell, and then enter your script. For example, you could enter the following text:

println "Hello"

You can then click Evaluate to run the script once. If it works without any errors, you can save the script to you can schedule it to run as a scheduled job. To save the script, enter a unique name for it, and then click Save. If you always want this script to run when the service registry starts, click Run on startup.

http://groovy.codehaus.org/

Modifying a Script Chapter 6 Working with Scripts


To use an existing script as a template for a new script, click the existing script on the right side of the screen, make your modifications, and then click Save As and enter a new name for the script.

Modifying a ScriptTo edit an existing script, click its name on the right side of the screen, make the modifications, and then click Save. At any time, you can click Reset to return to the last saved version of the script.

To delete a script, click it on the right side of the screen, and then click Delete.

Scheduling a ScriptYou can use the scheduler to periodically run your script, which is useful for jobs such as replication.

To create a scheduled job:

1 Click the Add link next to Scheduler on the Administration tab.


Chapter 6 Working with Scripts Scheduling a Script

2 Select the script to run.

3 Enter a unique name for this scheduled job.

4 Enter a cron command (see “Cron Command Syntax” on page 69) to specify when the script should be run.

5 Click Save.

Warning After you click Save to save the scheduled job, the script will run on the specified schedule until you delete the job.

To delete a scheduled job:

1 Click Scheduler on the Administration tab.

2 Click the scheduled job you want to delete.

3 Click Delete, and then click OK to confirm you want to delete this job.

Cron Command Syntax

You use the following syntax when specifying the cron command:

Field Name Mandatory Allowed Values Allowed Special Characters

Seconds YES 0-59 , - * /

Minutes YES 0-59 , - * /

Hours YES 0-23 , - * /

Day Of Month YES 0-31 , - * / L W

Month YES 1-12 or JAN-DEC , - * /

Day Of Week YES 1-7 or SUN-SAT , - * / L #

Year NO empty, 1970-2099 , - * /

Scheduling a Script Chapter 6 Working with Scripts


Following is a description of the special characters:

Following are some examples of cron commands:

Character Description

, Separates individual values, such as 0,30 in the minutes position to run the job on the hour and half hour.

- Specifies a range of values, such as MON-FRI in the Day Of Week position to run the job each day of the work week.

* Specifies all values for that position, such as every day of the week when * is specified in the Day Of Week position.

? Skips setting a value for that position. Since Day of Week and Day of Month are mutually exclusive, always use ? in one of these fields and specify * or a specific value for the other.

/ Specifies increments, such as every fifteen seconds starting on the first second of each minute when 1/15 is specified in the Seconds position.

L Specifies the last day of the month or week, depending on the position.

W Specifies the weekday nearest the specified day, such as running the job on the weekday closest to the third of the month when 3W is specified in the Day of Month position.

# Specifies a day of the week as it occurs in the month, such as running the job the second Friday of every month by specifying 6#2 in the Day of Week position (where 6 is the sixth day of the week, or Friday, and #2 specifies the second occurrence of that day in the month).

Command Description

0 0 12 * * ? 12pm (noon) every day. Note that no year is specified, because the year position is optional.

0 15 10 ? * * 0 15 10 * * ? 0 15 10 * * ? * 0 15 10 * * ? ?

Any of these commands runs the job at 10:15am every day

0 0/5 14 * * ? Every 5 minutes starting at 2pm and ending at 2:55pm, every day


Chapter 6 Working with Scripts Examples

For more information on the cron command and its options, see http://www.opensymphony.com/quartz/wikidocs/CronTriggers%20Tutorial.html

ExamplesThis section provides examples of using scripts.

Event Listener

This simple script listens for property changes to an item’s lifecycle and prints a line to the console every time that happens.

import org.mule.galaxy.event.*;import org.mule.galaxy.event.annotation.*;

// An event listener that fires emails when new entry versions are created@BindToEvent("PropertyChanged")public class ConsoleLifecycleNotifier {

@Async @OnEvent void onEvent(PropertyChangedEvent e) { if ("primary.lifecycle" == e.propertyName) println "Got lifecycle transition event for ${e.itemPath}" }}

// remove the previous listener, if any

0 0/5 14,18 * * ? Fire every 5 minutes starting at 2pm and ending at 2:55pm, AND fire every 5 minutes starting at 6pm and ending at 6:55pm, every day

0 0/5 14-16 * * ? Every 5 minutes starting at 2pm and ending at 4:55pm, every day

0 10,44 14 ? 3 WED 2:10pm and 2:44pm every Wednesday in March

0 15 10 ? * 6L 2010-2012 10:15am on the last Friday of every month during the years 2010, 2011, and 2012

Command Description

http://www.opensymphony.com/quartz/wikidocs/CronTriggers%20Tutorial.html

Examples Chapter 6 Working with Scripts


eventManager.listeners.each { if (it.class.simpleName == "ConsoleLifecycleNotifier") { eventManager.removeListener(it) println "Removed listener" }}

// add the event listener againeventManager.addListener(new ConsoleLifecycleNotifier())

Notification Script

This script watches for new artifact versions and sends an email to any user who is registered in the contacts property.

import org.mule.galaxy.event.*;import org.mule.galaxy.event.annotation.*;

import org.mule.galaxy.Registryimport org.mule.galaxy.security.Userimport org.mule.galaxy.Item

import javax.mail.*;import javax.mail.internet.*;

import java.util.Properties;

// An event listener that fires emails when new entry versions are created@BindToEvents(["EntryVersionCreated"])public class EmailNotifier {

def String userProperty = "contacts" def String server = 'smtp.foo.com' def String port = '465' def String username = 'XXXX' def String password = 'XXXX' def Registry registry @Async @OnEvent void onEvent(EntryVersionCreatedEvent e) { notifyUsers(e) }


Chapter 6 Working with Scripts Examples

void notifyUsers(ItemEvent e) { Properties props = new Properties();

props.setProperty("mail.host", server); props.setProperty("mail.user", username); props.setProperty("mail.smtp.port", port); props.setProperty("mail.password", password); props.setProperty("mail.smtp.auth", "true");

Item item = registry.getItemById(e.itemId); def mailSession = Session.getDefaultInstance(props, null); Transport transport = mailSession.getTransport("smtps"); MimeMessage message = new MimeMessage(mailSession); message.setSubject("Artifact/entry ${item.name} was created"); message.setContent("Artifact/entry was created in ${item.path}", "text/plain"); def contacts = item.getProperty(userProperty); contacts?.each { message.addRecipient(Message.RecipientType.TO, new InternetAddress(it.email)); } if (!contacts) { return };

transport.connect(); transport.sendMessage(message, message.getAllRecipients()); transport.close(); }}

// remove the previous listener, if anyeventManager.listeners.each { if (it.class.simpleName == "EmailNotifier") { eventManager.removeListener(it); println("Removed listener"); }}

// add the event listener againeventManager.addListener(new EmailNotifier(registry: registry));

Examples Chapter 6 Working with Scripts


Replicating Workspaces

You can replicate workspaces from one service registry instance to another. Replications are performed via custom scripts. This allows you to easily customize the replication process and schedule it via the Scheduler.

Replication occurs by copying artifacts and entries from one workspace to another. If you’re replicating to a remote service registry instance, you must first attach it as a remote workspace.

Once you have both your origin and destination workspace in mind, you can create a script that performs this replication. Following is an example script:

import org.mule.galaxy.ee.util.*;// Create a replicator called "myReplicator"def replicator = new Replicator(registry, activityManager, "myReplicator");

// Copy from the first workspace, to the second one.replicator.copy("/LocalWorkspace", "/RemoteWorkspace");

This script copies all artifacts and entries from LocalWorkspace to RemoteWorkspace. Note that it is beneficial to give your replicators an ID, in this case myReplicator. This makes it easy to view the actions of the replicator in the activity log.

Once you have saved this script, it is easy to schedule this script to be run periodically via the scheduler (see “Scheduling a Script” on page 68).


Chapter 7

Using Mule NetBoot

Mule NetBoot allows you to start and configure multiple instances of Mule simultaneously using the service registry. Mule NetBoot is a lightweight distribution of Mule that you can push out to remote nodes, each of which can point to the same service registry workspaces for centrally governed library distribution and configuration.

This chapter contains the following sections:

“Prerequisites” on page 75 “Quick Start” on page 76 “Installing Mule NetBoot” on page 78 “Running Mule NetBoot” on page 79 “Caching and Offline Mode” on page 81 “Mule NetBoot and JMX” on page 81

PrerequisitesBefore you can use Mule NetBoot, you must have Java 5 or later installed on the computer where you will run Mule NetBoot. You must also have at least one full distribution of Mule installed, which is required for a one-time upload of Mule libraries to the service registry.

To download Mule NetBoot, go to http://mulesupport.mulesource.com/portal/secure/app/download.mule and scroll down to the Service Registry Release table. Mule NetBoot is also part of the main Galaxy tree and is built along with the service registry for Mule ESB Enterprise and with Galaxy builds. When building from source, the distribution is available in the netboot/distributions/muleX/target folder.

Note that the current version of Mule NetBoot works only with JAR artifacts in the /user, /mule, and /opt subfolders under $MULE_HOME/lib.


Quick Start Chapter 7 Using Mule NetBoot


Quick StartThis quick start section will help you quickly learn how to publish applications to the service registry and start them remotely using Mule NetBoot. This section uses Mule as the example application.

Prerequisites

The quick start assumes that you have:

Installed Apache Maven (see http://maven.apache.org/).

Installed the standalone or WAR version of the service registry (see Chapter 2, “Getting Started.”)

Downloaded and unzipped the the service registry/Galaxy examples distribution (see http://mulesupport.mulesource.com/portal/secure/app/download.mule)

Downloaded and extracted the Mule NetBoot distribution and the latest Mule 2.x distribution

Publishing Applications to the Service Registry

This example uses a small Mule application called Background Check Service to show the capabilities of Mule NetBoot. The example contains a WSDL, a schema, a Mule configuration, and a simple web service implementation. You will publish these resources and a JAR of the application to be managed by the service registry.

First, use Maven to build the application and upload the appropriate resources to the service registry:

$ cd galaxy-examples-1.5.2/background-check-service$ mvn package

The Maven publishing plug-in is bound to the package goal of Maven, so whenever a distribution is made it is uploaded to the service registry instance. However, you might want to do this only when a release is made.

http://maven.apache.org/



Chapter 7 Using Mule NetBoot Quick Start

Setting Up Mule NetBoot

Next, you upload a Mule distribution to the service registry. To do this, use the upload_mule_to_galaxy script inside the Mule NetBoot distribution:

$ cd mule2-netboot-1.5.2/bin$ ./upload_mule_to_galaxy -m /path/to/mule-2.2.1

You’ll see many JARs being uploaded to the service registry, which Mule NetBoot will use later for its underlying Mule instance by downloading them as needed. These JARs will all be uploaded into the /Mule workspace by default.

To configure the upload_mule_to_galaxy script to use a different host/port or to put your Mule distribution in a non-default location, see “Mule NetBoot Parameters” on page 80.

Starting Mule via Mule NetBoot

Lastly, you use Mule NetBoot to load the Mule distribution and application to nodes over the network. Any computer that can connect to the service registry can be a node. Simply download Mule NetBoot on the node and extract it, point your MULE_HOME variable to its location, and run the mule script from the Mule NetBoot directory. Mule NetBoot starts up and connects with the service registry to download the necessary files.

By default, Mule NetBoot looks for the Mule instance in the /Mule workspace on localhost:8080. If your application is in a different location, you specify it as part of the command.

$ cd mule2-netboot-1.5.2/bin$ export MULE_HOME=/path/to/mule2-netboot-1.5.2$ ./mule -M-Dgalaxy.app.workspaces=Applications/BackgroundCheck

This quick start walked you through the fastest path to installing and using Mule NetBoot. The rest of this chapter describes the steps and options in more detail.

Installing Mule NetBoot Chapter 7 Using Mule NetBoot


Installing Mule NetBootWhen you install Mule NetBoot, you first upload a snapshot of the existing Mule libraries from a full distribution of Mule to the service registry. This is a one-time operation to prepare a unified snapshot for pushing out to remote nodes. Any custom and vendor libraries from $MULE_HOME/lib/user will also be included as part of the process. You then install the Mule NetBoot distribution on the remote nodes, which do not require the full Mule distribution.

To upload Mule:

1 Unpack the Mule NetBoot distribution on the computer where the full Mule distribution resides.

2 Ensure your servlet container has at least 128MB of memory. For example, for Tomcat, edit $TOMCAT_HOME/bin/catalina and set CATALINA_OPTS=-Xmx128m (this step is important).

3 Start the service registry, such as http://localhost:8080 if it’s on the same computer as the full distribution of Mule.

4 If you want to store your Mule configuration files in the application JARs so that Mule NetBoot nodes can download the configuration files automatically, copy the configuration files to $MULE_HOME/lib/user. For alternatives, see “Specifying the Mule Configuration File” on page 79.

5 If you want your Mule NetBoot nodes to be able to use the Galaxy configuration builder to read the configurations directly from the service registry, download and unpack the the Galaxy integration JARs (galaxy-integration-distribution-version.zip) into $MULE_HOME/lib/user. See “Installing the Plug-ins” on page 36 for more information.

6 If you use a properties file instead of specifying the properties at the command line, copy the properties file to $MULE_HOME/lib/user.

7 Switch to the bin folder under the Mule NetBoot home directory (such as mule2-netboot/bin), and then execute the following command:

upload_mule_to_galaxy -m <full Mule installation path>

where <full Mule installation path> is the fully qualified path to the existing Mule installation. For help on this command, type upload_mule_to_galaxy --help

You should see a splash screen followed by a series of JARs and HTTP 201 statuses (HTTP Created). You now have a Mule workspace created and configured in the service registry.


Chapter 7 Using Mule NetBoot Running Mule NetBoot

To install Mule NetBoot on an individual node:

1 On a computer where you will run Mule remotely, download and extract Mule NetBoot.

2 Configure MULE_HOME to point to the Mule NetBoot folder.

3 Repeat these steps for each computer where you want to run Mule remotely.

You are now ready to run Mule NetBoot.

Running Mule NetBootTo run Mule NetBoot, change to the mule2-netboot/bin directory, and then run the mule startup script with any necessary parameters (see page 80). This starts Mule NetBoot and downloads the necessary JARs remotely from the service registry. If the configuration files are not provided in the application JARs, you must specify the configuration as described below.

Specifying the Mule Configuration File

There are multiple ways to provide a Mule configuration to Mule NetBoot:

Use a local configuration file just as you would with the full Mule distribution. This is useful for testing, but because it involves copying the configuration file manually to each computer, it doesn’t scale well for production deployments. For example:

mule -config myConfig.xml -M-Dgalaxy.app.workspaces=MyMuleWorkspace

Use the Galaxy Configuration Builder to query and read configuration files directly from Galaxy. This approach is useful for ensuring that each node uses exactly the same file, but because they are using the file directly from the service registry, the nodes cannot access the configuration if the service registry server becomes unavailable. For more information, see “Mule 2.x Integration” on page 36.

Store the configuration files in a JAR and copy them to $MULE_HOME/lib/user before uploading the files to the service registry. The configuration JAR is installed in the service registry, and then individual nodes download and use the configuration locally. This is a good hybrid approach, because the configuration is distributed to nodes automatically, but Mule NetBoot still gets to work with a local copy of the configuration file, which is useful if the service registry server becomes unavailable. This is the default behavior, so if you do not specify a configuration file when running Mule NetBoot, it assumes that the configuration file is stored in an application JAR.

Running Mule NetBoot Chapter 7 Using Mule NetBoot


Mule NetBoot Parameters

Most parameters just have default values. Mule NetBoot accepts some extra parameters to customize the Mule NetBoot process, each of which you prefix with -D:

The properties are set as system properties. To pass these parameters directly to the Mule NetBoot layer, use the -M switch. For example:

mule -M-Dgalaxy.app.workspaces=MyMule-Dgalaxy.port=9020

Booting from Multiple Workspaces

You can split user application libraries into multiple logical workspaces and still boot as if they were one. To do this, specify custom workspaces separated by commas in the galaxy.app.workspaces switch, as described above.

Note Only user workspaces are splittable. Mule’s system NetBoot workspace structure (holding Mule JARs) is fixed.

Name Description Default Notes

galaxy.host Service registry host localhost

galaxy.port Service registry port 8080

galaxy.apiUrl Galaxy API URL /api/registry

galaxy.username Service registry username admin

galaxy.password Service registry password admin

galaxy.netboot.workspace Workspace to load system Mule JARs from

Mule Since 1.0-beta-3

galaxy.app.workspaces A comma-separated list of workspaces to load user application JARs from

<empty> Since 1.0-beta-3

galaxy.debug Output some debug info false

galaxy.clean Delete cached and temp download files

false Since 1.0-beta-3


Chapter 7 Using Mule NetBoot Caching and Offline Mode

Caching and Offline ModeDownloaded JARs are cached. On each subsequent launch, the service registry checks for available updates and downloads corresponding artifacts. If the service registry is unavailable, or if there’s a network issue, Mule NetBoot goes into an offline mode, working with the previously cached resources. Note the following:

Caches must be available A launched Mule might not match the one in the service registry (offline) Currently, there’s no switch to enforce offline mode for Mule NetBoot

Mule NetBoot and JMXMule NetBoot comes with JMX bindings that allow you to easily manage Mule NetBoot instances remotely. By allowing remote management, you can centrally manage your applications by triggering updates and rollbacks from the JMX console. For information on using jconsole, which comes with the JDK, see the jconsole documentation at http://java.sun.com/j2se/1.5.0/docs/guide/management/jconsole.html.

http://java.sun.com/j2se/1.5.0/docs/guide/management/jconsole.html


Appendix A

Galaxy Query Language

Galaxy Query Language (GQL) is a SQL-like query language you can use when searching via the web interface or the HTTP Atom Publishing Protocol API. This appendix describes how to use GQL and provides several examples.

Basic UsageGQL allows you to query a set of artifacts or artifact versions that match a set of properties. The simplest statement selects all artifacts:

select artifact

Or every version of every artifact:

select artifactVersion

To narrow down the search to a particular workspace, use the from clause:

select artifact from '/some/workspace';

To find all artifacts that have a certain property, use the where clause. This example shows how to select all WSDL documents that have a WSDL <service> element named HelloWorldService:

select artifact where wsdl.service = 'HelloWorldService';

This statement selects all artifacts that have a Mule service named GreeterUMO or FooUMO.

select artifact where mule.descriptor in ('GreeterUMO', 'FooUMO')


Appendix A Galaxy Query Language Artifact Properties

Artifact PropertiesIn addition to artifact metadata, which is supplied by the user or is extracted from indexes, GQL includes support for a number of other properties:

For more information on artifact metadata, see “Working with Metadata” on page 30.

Statement StructureGQL statements are structured as follows:

select [artifact|artifactVersion] from 'workspace/path' where property [=|!=|like|in] [value] (and ...)

Property Description

name The name of the artifact

documentType The XML document type of the artifact (if any) in the form of {namespace}local-name

description The artifact description

contentType The artifact’s media type

phase The artifact’s current lifecycle phase


Aactivity monitoring 15additional resources 17Admin shell 67administration 48Administrators group 49Apache CXF

Galaxy Feature 41integrating via API 42integrating via XML configuration 41integrating with the service registry 41WS-Policy 41

API 35applications

deploying 14architecture 17artifact types

creating 56deleting 57editing 57

artifactsabout 28adding metadata to 30applying lifecycles to 31creating dependencies for 31dependencies 14details of 13editing multiple 33lifecycles 13managing 12managing types 56searching 13, 32, 83types of 29uploading groups of 23

Atom feeds 34

Atom Publishing Protocol 15, 35, 82audience for this guide 7authentication

LDAP 51

Bbackend database 21

switching 23backward compatibility requirement 27BasicProfile compliance policy 27BLOBs 22, 24bulk editing 33

Ccaching 81change notifications

subscribing to 34ClassNotFoundException 23client remoting policy 27clustering 16, 21collaboration 11comments

subscribing to changes 34compliance policy 27configuration files

specifying with Mule NetBoot 79configuration utility 21container memory 78content type 56, 61, 83contract management 10

Index


Index

cron commandsentering 69examples 70special characters 70syntax of 69

curl command 23customizing the service registry 14CXF

see Apache CXF

Ddatabase 21Delete Artifact/Entry permission 50Delete Workspace permission 50dependencies 14

creating 31deployment

management 14phases 11

Derby 21distinguished name 54document type 83documentation

typographic conventions 8downloading the service registry 20

Eediting multiple objects 33endorsing Xerces 19endpoints policy 27Enterprise Edition features 16entries 33

about 28adding metadata to 30searching 32

environment settings 20error messages

ClassNotFoundException 23Invocation of init method failed 24OutOfMemoryError 24schema validation 19

event listenerexample script 71

Execute Admin Scripts permission 50expressions

XPath 58XQuery 59

extensionscreating for the service registry 14working with scripts 67

Ffailover 21fault tolerance 16features 12

Enterprise Edition 16federation 16feeds 34filtering 32frequently asked questions 23

GGalaxy API 35Galaxy Configuration Builder

using with Mule NetBoot 79Galaxy CXF Feature 41Galaxy Publishing plug-in for Maven 43Galaxy Query Language (GQL) 82GalaxyConfigurationBuilder

starting Mule from 36, 39global endpoints policy 27global metadata 30governance 9

applying policies 28, 63monitoring registry activity 65

GQL 82Groovy scripting language 67groups

Administrators 49creating 51deleting 51editing 51LDAP 52managing 49permissions 50

groupSearchFilter property 55


Index

Hhigh availability 16, 21HTTP endpoints

requiring SSL 27httpPort argument 21

Iimports

linking artifacts via 31indexes 15

creating 60default 57deleting 61editing 61managing 57Mule 1.x 40Mule 2.x 38XPath 57XQuery 58

initialDirContextFactory bean 54installing your service registry license 66integrating applications with the service

registry 35Apache CXF 41Maven 43Mule 1.x 39Mule 2.x 36Spring 43

interoperability 11Invocation of init method failed error 24

JJava versions supported 19JAXB libraries 24JCR repository 21JDBC driver 23JMX 81JMX monitoring policy 27JVM memory 20

LLDAP

creating the configuration file 52enabling authentication through 51enabling the configuration file 55JAR file 52properties 54

LdapAuthoritiesPopulator bean 55license file

installing 66lifecycle management 13lifecycles

applying policies to 63applying to artifacts 31creating 62managing 30, 62removing policies from 63

Linux file handles 20load balancer 21logging in to the service registry 23

MManage Artifact Types permission 50Manage Groups permission 50Manage Indexes permission 50Manage Lifecycles permission 50Manage Policies permission 50Manage Properties permission 50Manage Users permission 50managerDn property 54managerPassword property 54Maven

adding the service registry repository to your POM 44

configuring security 46configuring the plug-in 45integrating with the service registry 43

media type 56, 61, 83memory 78memory requirement 20metadata 13

creating 28, 30global 30versioned 30


Index

migrating existing databases 23MIME type 56, 61, 83Modify Artifact/Entry permission 50Modify Workspace permission 50monitoring registry activity 15, 65MS Office 16Mule 1.x

indexes 40integrating with the service registry 39properties 40starting from code 39starting from scripts 39starting with properties 39

Mule 2.xindexes 38integrating with the service registry 36properties 38starting from code 37starting from Mule NetBoot 77starting from scripts 37starting with properties 37uploading to the service registry 77, 78

Mule NetBoot 14and JMX 81booting from multiple workspaces 80downloading 75installing 78, 79offline mode 81parameters 80prerequisites 75quick start 76specifying the configuration file 79starting 79starting Mule from 77uploading Mule 78uploading Mule to the service registry 77using 75

MuleSource Technical Support 8MySQL 21

NNetBoot

see Mule NetBootno client remoting policy 27

non-local endpoints policy 27notification script example 72notifications 34

Ooffline mode 81Oracle, MSSQL 21OutOfMemoryError 24

Ppermissions 50phases

adding to a lifecycle 63plug-ins

API 35installing 36integration 35

policiesand collaboration 11applying to lifecycle phases 63applying to workspaces 28default 27enforcement 14loading into the service registry 41managing 63Mule 27removing from lifecycle phases 63require JMX 27require no client remoting 27require non-local endpoints 27require SSL 27SSL-encrypted HTTP 14WSDL 27WSDL backward compatibility 14WS-I BasicProfile compliance 14

port setting 21PostgreSQL 21prerequisites

for running the service registry 19for WAR configuration 22


Index

propertiescreating manually 62extracting via indexes 57Mule 1.x 40Mule 2.x 38searching 83starting Mule using 37, 39

QQName 61qualified name 56, 61queries 82

using 32query engine 16

RRead Artifact/Entry permission 50Read Workspace permission 50registry activity

monitoring 65remote workspaces 16, 64remoting policy 27replication 16, 68

example 74repository 29

adding to your POM 44rollbacks 11RSS feeds 34rules

see policiesrunning the service registry 20, 21, 23

Ssaving searches 32scheduled jobs

creating 68deleting 69

scriptsabout 67Admin shell 67deleting 68editing 68examples 71Groovy language 67scheduling 68

searching 13, 16, 32saving results 32

securityconfiguring in the service registry 48enabling authentication through LDAP 51

service registry WAR 21service-oriented architecture (SOA) 9services

creating metadata for 28discovery 10

servlet container 21special characters

in cron commands 70Spring

integrating with the service registry 43SSL policy 27SSL-encrypted HTTP policy 14staged deployments 11standalone mode 20starting the service registry 20, 21, 23subscribing to change notifications 34suggested reading 17support 8supported versions 19

TTCP endpoints

requiring SSL 27technical support 8Tomcat 78typographic conventions 8

UUDDI 24UNIX file handles 20


Index

upload_mule_to_galaxy script 77uploading Mule to the service registry 77, 78userManager bean 55users

creating 49deleting 49editing 49managing 49

userSearch bean 55userSearchAttributes property 55userSearchBase property 55

Vversion feeds 34versioned metadata 30versioning

requiring backward compatibility for WSDL 27

rolling back 14View Activity Log permission 50views

creating 32, 33deleting 33

WWAR file 21web services

interoperability 11workspaces 11

applying policies to 28creating 26managing 26remote 16, 64replicating 16, 74searching 13splitting applications across 80

WSDL backward compatibility 11, 14WSDL documents

policies 27WS-I BasicProfile compliance 11, 14

policy 27WS-Policy documents 41

XXerces

endorsing 19XPath indexes 15, 57XQuery indexes 15, 58

201 Mission StreetSuite 1380San Francisco, CA 94105Phone: 877-MULE-OSS (877-685-3677)Fax: 415-358-8573www.mulesource.com

http://www.northstar.com

Documents

Service Registry