@jpf:controller Annotation

Syntax

@jpf:controller

[ nested = "true | false" ]

[ login-required = "true | false" ]

[ roles-allowed = "<J2EE-role-name> [ , <J2EE-role-name> ] " ]

[ struts-merge = "<Struts-file>.xml" ]

Attributes

nested

Optional. A boolean that indicates whether this is a nested page flow that can be called from another page flow. If the @jpf:controller annotation is used, but the nested attribute is not, the default is nested="false".

Optional. A boolean that indicates whether the user must be logged-in to use this page flow. If the @jpf:controller annotation is used, but both the login-required and roles-allowed attributes are not used, the default is login-required="false". However, if only the roles-allowed attribute is used, then login-required="true" is implied.

The JPF compiler will issue an error if you use both the roles-allowed attribute and the login-required attribute.

roles-allowed

Optional. Specifies the name of one or more J2EE roles that are defined in the web project's /WEB-INF/web.xml file. If more than one J2EE role name is specified, use a comma to separate each name. If defined, the use of all action methods in this page flow is limited to users who are associated with the specified role(s). Note that users who are granted the roles specified may access all methods in the page flow, regardless of any further role restrictions applied to individual methods by the @jpf:action annotation.

You can, optionally, also use the @jpf:action annotation to add to the authorized role(s) that are declared at the class-level by @jpf:controller. The method-level @jpf:action annotation also has a roles-allowed attribute. For more information, see @jpf:action annotation.

struts-merge

Optional. Specifies a standard Struts configuration XML file that you want the WebLogic Workshop compiler to merge into the generated configuration file for the page flow: /WEB-INF/jpf-struts-<pageflow-name>.xml. The Struts XML file, by convention, should reside in the web project's /WEB-INF directory. After the compilation step that creates the merged /WEB-INF/jpf-struts-<pageflow-name>.xml, functionality that was enabled by the Struts configuration is available to the page flow controller.

The purpose of the "Struts Merge" feature is to enable you to override page flow defaults, or to specify settings for the page flow that are not provided by page flow annotations or their attributes. The Struts merge files should typically be small and only modify the page flow and its actions and form beans. You can also add Struts tags that are not supported by page flows, such as the <plug-in> tag. While you could, for example, add action mappings in the Struts merge file, BEA does not recommend this practice. Struts action mappings should be declared in the page flow's .jpf file with @jpf annotations, and then (if necessary) modified with the Struts merge file. For details, see Merging Struts Artifacts Into Page Flows.

Remarks

The following rules apply to this annotation's use:

The @jpf:controller annotation is optional and can be used only to qualify the page flow class. This annotation cannot be used on a method within the page flow class.
A nested page flow is useful when you want to perform some processing and then return (with or without the results) to the calling page flow. For example, a vacation scheduling page flow could call a nested page flow that lists the company holidays. After the companyHolidays page flow is used, a method that exists in the nested page flow could return the user to the calling vacationScheduling page flow.
The roles-allowed attribute on this @jpf:controller annotation lets you limit access to this page flow's action methods to users who are associated with the security role. This, in turn, limits access from the current context to the web resource that would be loaded as a result of the action. Again, you can add to the authorized role(s) declared at the class-level with @jpf:controller by using the roles-allowed attribute on a method-level @jpf:action annotation.
Note that the following IDE menu option defines a new security role in the application's /META-INF/application.xml file:

Tools > Security > Create New Security Role...

However, /META-INF/application.xml is not the XML file that is used for the page flow scoped roles-allowed checking. Enter any security roles in the web project's web.xml file, and associate principals with the role name in the web project's weblogic.xml file. For more information, see the Role-Based Security.