fabric3
Content
Documentation
Developer Reference
Policy
Policy
search
attachments
weblink
advanced
image-effects
image-attributes
Paragraph
Paragraph
Heading 1
Heading 2
Heading 3
Heading 4
Heading 5
Heading 6
Preformatted
Quote
Bold
Italic
Underline
Colour picker
More colours
Formatting
Strikethrough
Subscript
Superscript
Monospace
Clear formatting
Bullet list
Numbered list
Task list
Outdent
Indent
Align left
Align center
Align right
Page layout
Link
Table
Insert
Insert content
Files and images
Link
Symbol
Emoticon
Markup
Horizontal rule
Insert macro
User mention
Jira Issue/Filter
Info
Status
Gallery
Table of Contents
Jira timeline
Lucidchart Diagrams
Trello Board
Other macros
Page layout
No layout
Two column (simple)
Two column (simple, left sidebar)
Two column (simple, right sidebar)
Three column (simple)
Two column
Two column (left sidebar)
Two column (right sidebar)
Three column
Three column (left and right sidebars)
Find/Replace
Keyboard shortcuts help
You are not logged in. Any changes you make will be marked as
anonymous
. You may want to
Log In
if you already have an account.
<p>Fabric3 supports an extensible interceptor framework for implementing cross-cutting policies based on SCA. Policies are used to implement behaviors such as transactions, security, or SLA alerts. Policy interceptors are enabled in three ways:</p> <ul> <li>Declared explicitly using Java annotations or in a composite</li> <li>Externally "attached" using XPath pattern matching at deployment</li> <li>Dynamically using XPath pattern matching against existing components</li> </ul> <p>Policies can be thought of as a type of Aspect Oriented Programming (AOP) for services. However, instead of applying to OO constructs such as classes and methods, policies can also be defined to apply to services, components, and remote communications. Further, policies can be applied across applications and dynamically after components have been deployed, even in a cluster.</p> <p>Policies are an extremely useful feature for reducing application complexity. For example, security code can be implemented as a policy and reused across applications. This isolates complexity in a single place and avoids the error-prone task of repeating a task multiple times. </p> <table class="wysiwyg-macro" data-macro-name="info" data-macro-schema-version="1" style="background-image: url(https://fabric3.atlassian.net/wiki/plugins/servlet/confluence/placeholder/macro-heading?definition=e2luZm99&locale=en_GB&version=2); background-repeat: no-repeat;" data-macro-body-type="RICH_TEXT"><tr><td class="wysiwyg-macro-body"> <p>The samples provide an example of implementing a custom policy that intercepts operation calls for services and counts invocations.</p></td></tr></table> <h2>Concepts</h2> <p>Policies are commonly used without needing to delve into the details of how they are enabled. For example, Fabric3 transaction support is built on the policy framework. However, to make use of transactions, one need only understand transaction semantics and how to apply the <code>@ManagedTransaction</code> annotation:</p> <table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="java" data-macro-schema-version="1" style="background-image: url(https://fabric3.atlassian.net/wiki/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6amF2YX0&locale=en_GB&version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre> @ManagedTransaction public class MyTransactionalComponent { // ... } </pre></td></tr></table> <p>The specifics of SCA policy are beyond the scope of this reference. Briefly, though, intents are abstract requirements that can be declared by a component or on a reference or service. Intents are matched to policy sets, which provide concrete configuration for a behavior. For example, a "message authentication" intent may be mapped to a policy set that specifies WS-Security or HTTP Basic Auth. Intents are therefore a way to specify a requirement without tying a component to a specific underlying technology. For transports that do not use WS-Security or HTTP, the "message authentication" intent could be mapped to a different security technology, such as a security API used by a JMS provider.</p> <p>Intents may be specified using Java annotations or via the <code>@requires</code> attribute or as part of a composite XML.</p> <h2>Creating Custom Policies</h2> <p>Policies are defined in a definitions file, <code>definitions.xml</code>, that is deployed as part of a contribution archive. The definitions file can contain <em>intents</em>, <em>policy sets</em>, <em>binding types</em>, and <em>implementation types</em>. Custom policies may be bundled directly with user code (e.g. if it is only applicable to a service or set of services) or as a separate contribution.</p> <h3>Defining and Applying Policies</h3> <p>Implementing a custom policy involves implementing and configuring an interceptor that will be called to process a message during an invocation. The following XML definitions file demonstrates how to define an interceptor policy:</p> <table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="xml" data-macro-schema-version="1" style="background-image: url(https://fabric3.atlassian.net/wiki/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6eG1sfQ&locale=en_GB&version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre> <definitions xmlns="[http://docs.oasis-open.org/ns/opencsa/sca/200903|http://docs.oasis-open.org/ns/opencsa/sca/200903]" xmlns:f3="urn:fabric3.org"> <policySet name="testImplementationPolicy" f3:phase="INTERCEPTION" attachTo="//component"> <f3:interceptor class="org.fabric3.interceptor.TestInterceptor"/> </policySet> </definitions> </pre></td></tr></table> <p>The above example uses external attachment to enable policy. The "attachTo" attrbitute instructs Fabric3 to apply the interceptor to all components in the domain (note you would probably not want to do this in a real-world application). Again, the details of these SCA mechanisms are beyond the scope of this reference. Briefly, though, the value of the attachTo attribute is an XPath expression that is applied to the domain infoset. This is an extremely powerful capability as policies can be dynamically attached to any component, binding, or wire in the domain by specifying an XPath expression. This attachment can happen at deployment or be applied to already deployed components, bindings, and wires. </p> <p>Note that in addition to external attachment, Fabric3 also supports a "pull" policy model where policies (or intents) are specified in the component configuration or via annotations.</p> <p>The interceptor class for the previous policy set is shown below:</p> <table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="java" data-macro-schema-version="1" style="background-image: url(https://fabric3.atlassian.net/wiki/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6amF2YX0&locale=en_GB&version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre> package org.fabric3.interceptor; import org.fabric3.spi.invocation.Message; import org.fabric3.spi.wire.Interceptor; public class TestInterceptor implements Interceptor { private Interceptor next; public Message invoke(Message message) { // perform some processing. return next.invoke(message); } public void setNext(Interceptor interceptor) { next = interceptor; } public Interceptor getNext() { return next; } } </pre></td></tr></table> <p>Note the interceptor class implements <code>org.fabric3.spi.wire.Interceptor</code>, which is located in the Fabric3 SPI archive (fabric3-spi.jar). </p> <h3>Including Policies in a Contribution</h3> <p>Policies (e.g. the definitions.xml file and supporting classes such as an interceptor) can be packaged and deployed as part of a contribution. This is useful if the policy only applies to a particular set of services. The only required step to do this is to ensure the contribution manifest (sca-contribution.xml) contains an import.java entry for the org.fabric3.spi package:</p> <table class="wysiwyg-macro" data-macro-name="code" data-macro-schema-version="1" style="background-image: url(https://fabric3.atlassian.net/wiki/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGV9&locale=en_GB&version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre> <contribution xmlns="http://docs.oasis-open.org/ns/opencsa/sca/200903" xmlns:f3="urn:fabric3.org"> <import.java package="org.fabric3.spi.*"/> </contribution> </pre></td></tr></table> <h3>Packaging Policies Separately</h3> <p>Policies can also be packaged and deployed as individual contributions. Again, the only specific requirement is that the contribution manifest import the <code>org.fabric3.spi</code> package. One important difference, however, with this approach is that the interceptor class will be loaded in a different classloader than the source and targets of a wire. In most cases, this will not matter as the component classloaders will not be needed. In cases where the source and target classloaders must be accessed, the policy contribution must use the lower level Fabric3 interceptor builder SPI to obtain references to the appropriate classloaders. </p> <h3>Creating Custom Intent Annotations</h3> <p>Custom intent annotations can be created by using the <code>@Intent</code> meta-annotation. When <code>@Intent</code> is applied to an annotation, Fabric3 will detect the annotation and apply its corresponding intent. For example, the SCA <code>org.oasisopen.sca.annotation.Authentication</code> intent is defined in this manner: </p> <table class="wysiwyg-macro" data-macro-name="code" data-macro-default-parameter="java" data-macro-schema-version="1" style="background-image: url(https://fabric3.atlassian.net/wiki/plugins/servlet/confluence/placeholder/macro-heading?definition=e2NvZGU6amF2YX0&locale=en_GB&version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre> @Inherited @Target({TYPE, FIELD, METHOD, PARAMETER}) @Retention(RUNTIME) @Intent(Authentication.AUTHENTICATION) public @interface Authentication { String AUTHENTICATION = SCA_PREFIX + "authentication"; String AUTHENTICATION_MESSAGE = AUTHENTICATION + ".message"; String AUTHENTICATION_TRANSPORT = AUTHENTICATION + ".transport"; /** * List of authentication qualifiers (such as "message" or "transport"). * * @return authentication qualifiers */ @Qualifier String[] value() default ""; } </pre></td></tr></table> <p>When the Fabric3 runtime encounters <code>@Authentication</code> on a class, it will apply the "SCA authentication" intent to it.</p>
Save
Close
Edit
Preview
View changes
Revert to last published version
{"serverDuration": 392, "requestCorrelationId": "09592e05d8944036a465a29fcd159927"}