3 Using the WLS RESTful Management Interface
Note:
WebLogic Server Multitenant domain partitions, resource groups, resource group templates, virtual targets, and Resource Consumption Management are deprecated in WebLogic Server 12.2.1.4.0 and will be removed in the next release.
This chapter includes the following sections:
Accessing REST Resources
Each REST resource method documents which user roles can access it: Admin, Deployer, Operator, Monitor.
In general:
-
You must be in the Admin, Deployer, Operator, or Monitor role to read resources (use the
GET
method). -
You must be in the Admin role to write resources (use the
POST
andDELETE
methods) or to invoke operations (usingPOST
). -
However, with certain resources, a Deployer can deploy and undeploy applications and libraries, and an Operator can start a server.
If the user is a domain user (for example, defined in the domain's default security realm), the URL to access REST resources starts with http://host:port/management
. If the user is a partition user (for example, defined in that partition's security realm), the URL to access REST resources starts with http://host:port/
partition_name
/management
.
For more information about user roles in WebLogic Server Multitenant, see Administrative Roles for Configuration and Management in Using Oracle WebLogic Server Multitenant.
Viewing WLS Beans
To view a WLS bean, invoke the HTTP GET
method on its corresponding REST URL.
For example, to get the configuration for the server, Server-0
:
GET http://localhost:7001/management/weblogic/latest/edit/servers/Server-0
GET
returns a standard WLS REST response body. It returns a JSON object containing the bean's properties and a links
property, a JSON array containing links to related resources.
About WLS Bean Properties
The returned JSON object contains the WLS bean's properties (for example, typical properties and references, but not children), using the standard Java to JSON mappings (see JSON Mappings). It also includes an identity
property that specifies the bean's identity. For example:
{ identity: [ "domain", "servers", "Server-0" ], name: 'Server-0', listenPort: 7001, machine: { identity: [ "domain", "machines", "Machine-0" ] } }
Self and Canonical Links
All resources include a self
and a canonical
top level link that refer to the resource. For example, a server contains self
and canonical
links that refer to the specified server:
{ links: [ { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0" } { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0" } ] }
The cross-references of these links refer to that REST resource also, therefore, include the name of the tree in which the resource is a child, for example, edit
, domainRuntime
, serverConfiguration
, and such.
Parent Links
All resources, except for root resources, include a top level link to their parent resource. The link's rel
property is set to parent
.
Collection children return links to the collection resource, for example, a server returns a link to the server's collection resource:
{ links: [ { rel: "parent", href: "http://localhost:7001/management/weblogic/latest/edit/servers" } ] }
Similarly, singleton children return links to their parent resource, for example, an SSL bean returns a link to the server bean:
{ links: [ { rel: "parent", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0" } ] }
Self Create Form Links
If a bean is a creatable, optional singleton (for example, a realm's RDBMSSecurityStore
), and the bean currently does not exist, then a link to its corresponding create form resource is also returned. The link's rel
property is set to create
. For example, calling GET
on a security realm's adjudicator also returns:
{ links: [ { rel: "create", href: "http://localhost:7001/management/weblogic/latest/edit/securityConfiguration/realms/myrealm/adjudicatorCreateForm" } ] }
Child Bean Links
Since a WLS bean's containment properties (for example, children) are mapped to separate REST resources, they are returned as top level links in the JSON response body.
Each link's rel
property is mapped to the bean property's name. For example, calling GET
on Server-0
returns:
{ links: [ // mandatory singleton child: { rel: "SSL", href: "http://localhost:7001/management/weblogic/latest/servers/Server-0/SSL" }, // writable collection of children: { rel: "networkAccessPoints", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0/networkAccessPoints" } ] }
Child Create Form Links
Links to create form resources are returned for creatable containment properties (singletons and collections). The link's rel
property is set to <singularPropertyName>CreateForm
. For example, calling GET
on Server-0
also returns:
{ links: [ { rel: "networkAccessPointCreateForm", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0/networkAccessPointCreateForm" } ] }
Singleton Bean Reference Links
WLS beans return top level links for each non-null singleton reference. The link's rel
property is set to the name of the reference property. For example, if Server-0
refers to Machine-0
:
{ machine: [ "machines", "Machine-0" ], links: [ { rel: "machine", href: "http://localhost:7001/management/weblogic/latest/edit/machines/Machine-0" } ] }
If Server-0
has no machine reference:
{ machine: null }
Bean Reference Collection Links
WLS beans return nested links for each reference in a reference collection. The link's rel
property is set to self
.
For example, if Application-0
refers to the targets Server-0
and Cluster-0
:
{ targets: [ { identity: ["clusters", "Cluster-0" ], links: [ { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/clusters/Cluster-0" } ] }, { identity: ["servers", "Server-0" ], links: [ { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-0" } ] } }
Operation Links
Resources also return top level links to their operation resources. The links' rel
properties are set to action
and the links' titles are set to the name of the operation. For example, a ServerRuntimeMBean
returns:
{ links: [ { rel: "action", title: "suspend", href: "http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/suspend" }, { rel: "action", title: "resume", href: "http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/resume" }, { rel: "action", title: "shutdown", href: "http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/shutdown" } ] }
Viewing Collections of Contains Beans
To view a collection of WLS beans, invoke the HTTP GET
method on its corresponding REST URL.
For example, to get the configuration of all the servers:
GET http://localhost:7001/management/weblogic/latest/edit/servers
GET
returns a standard WLS REST response body. items
contains the children's properties. Each item has embedded self
and canonical
links to that child's resource.
Only the immediate children are returned. For example, if you get the servers collection, each server's properties will be returned, but the server's children (such as SSL) are not returned.
About Collection items
The resource returns a JSON object for each child in the collection. These objects contain the same data as the items returned from calling GET
on the children's resources. For example, getting the domain bean's servers
collection returns:
{ items: [ { name: "Server-1", listenPort: 7001, ... }, { name: "Server-2", listenPort: 7003, ... } ] }
About Collection Links
A collection resource returns the following links:
-
self
andcanonical
links to itself. -
A link to its parent.
-
A link to its corresponding create form resource if the collection is writable.
-
Nested
self
andcanonical
links to each of its children.
For example, getting the domain bean's servers
collection returns:
{ items: [ { name: "Server-1", listenPort: 7001, links: [ { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-1" } { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-1" } ] }, { name: "Server-2", listenPort: 7005, links: [ { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-1" } { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/servers/Server-1" } ] } ] links: [ { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers" } { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/servers" } { rel: "parent", href: "http://localhost:7001/management/weblogic/latest/edit" } { rel: "create-form", href: "http://localhost:7001/management/weblogic/latest/edit/serverCreateForm" } ] }
Retrieving Create Forms
To retrieve a create form for creating a new resource, invoke the HTTP GET
method on its corresponding create form REST URL.
For example, to retrieve a create form for creating a new server:
GET http://localhost:7001/management/weblogic/latest/edit/serverCreateForm
GET
returns a standard WLS REST response body. It returns a JSON object containing the create form's properties and a links
property which is a JSON array containing links to related resources.
About Create Form Properties
The returned JSON object contains a property for each writable property (normal properties and references) that may be specified when creating a new resource of that type. The property's value will either be the default value from the type's bean info (if available), or the default value for the property's type (for example, 0
for an int
). The values for reference properties are always null. For example, getting the domain's serverCreateForm
returns:
{ name: null, // identity - unique names are not generated idleConnectionTimeout: 65, // from the default value in the bean info replicationGroup: null, // default value for a String since the bean info does not provide a default value machine: null, // singleton reference candidateMachines: null, // reference collection ... }
About Create Form Links
A create form returns the following links:
-
self
andcanonical
links to itself. -
A link to its parent.
-
A
create
link to the corresponding resource that can be used to create a resource of this type.
For example, getting the domain bean's serverCreateForm
returns:
{ links: [ { rel: "parent", href: "http://localhost:7001/management/weblogic/latest/edit" }, { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/serverCreateForm" }, { rel: "canonical", href: "http://localhost:7001/management/weblogic/latest/edit/serverCreateForm" }, { rel: "create", href: "http://localhost:7001/management/weblogic/latest/edit/servers" } ] }
Filtering Results
Bean, collection, and create form resource GET
methods support these query parameters to let you omit properties and links from the response.
Parameter Name | Description |
---|---|
|
Only return these properties. |
|
Return all properties except for these properties. |
|
Only return links with these |
|
Return all links except for the ones with these |
fields
and excludeFields
are mutually exclusive, as are links
and excludeLinks
. All the values are comma-separated lists of names.
For example, to only retrieve a server's self
and parent
links, and name
and listenPort
properties:
curl ... -X GET http://localhost:7001/management/weblogic/latest/edit/servers/myserver\ ?fields=name,listenPort\&links=self,parent { links: [ { rel: "parent", href: "http://localhost:7001/management/weblogic/latest/edit/servers" }, { rel: "self", href: "http://localhost:7001/management/weblogic/latest/edit/servers/myserver" } ], name: "myserver", listenPort: 7001 }
Modifying the WLS Configuration
You can create, modify and delete beans in the edit tree only (.../management/weblogic/<version>/edit/...
). The other bean trees are read-only.
All WLS bean edits must be performed within a configuration transaction:
-
If you already have started a transaction, the REST changes will be made in the same transaction. You will still be responsible for committing or rolling back the transaction.
-
If you have not started a transaction, the REST resource will begin a transaction on your behalf, try to make the changes, and either commit or roll back the transaction depending on whether the changes could be made (auto-transactions).
-
If someone else already has started a transaction, the REST resource will return an error (instead of modifying the configuration).
Sometimes a configuration transaction cannot be committed unless complementary changes to multiple beans are made in the same transaction. In these cases, you need to begin and end the transaction explicitly versus relying on auto-transactions.
Also, when the client manages the transaction, each REST call saves the changes (but does not activate them). There is some MBean validation that occurs during the save operation which might cause it to fail. For example, when you create a JDBC system resource, the changes cannot be saved until after its child JDBC resource name is set. For cases like this, use the saveChanges=false
query parameter.
See the changeManager resources in RESTful Edit Reference for Oracle WebLogic Server.
Modifying WLS Configuration Beans
To modify a WLS bean, construct a JSON object containing the values you want to change then invoke the HTTP POST
method on its corresponding REST URL, passing in that JSON object as the request body.
For example, to change a server's listen port and administration port:
curl ... -d "{ listenPort: 7007, administrationPort: 9007 }" -X POST http://localhost:7001/management/weblogic/latest/edit/servers/Server-0
This is similar to an HTTP PATCH
operation where you only modify part of the bean, versus needing to pass in all of the bean's properties every time.
About the JSON Object Request Body
You construct a JSON object containing the values you want to change. Some WLS bean properties are read-only (for example, a server's name). Read-only properties are ignored.
You don't have to pass in all of the bean's properties. Any properties not passed in will retain their current values. As was described in Encrypted Properties, GET
returns the value @Oracle_Confidential_Property_Set_V1.1#
for an encrypted string property that has a non-null value. If you POST
back this value, then the property will retain its current value. If you want to change the encrypted property's value, then set the value to the cleartext string that you want it to be, for example:
{ defaultIIOPPassword: "admin123" }
To change a reference, pass in its identity. The same is true for reference collections. This replaces the reference collection versus adding references to the collection. For example, to set a server's machine to Machine-0
and candidate Machines to Machine-0
and Machine-1
:
{ machine: [ 'machines', 'Machine-0' ] }, candidateMachines: [ { identity: [ 'machines', 'Machine-0' ] }, { identity: [ 'machines', 'Machine-1' ] } ] }
Also, use null to remove references. For example, to remove a server's machine and candidate machines' references:
{ machine: null, candidateMachines: null }
If you pass in a mixture of valid and invalid values, the valid ones are written and errors are returned for the invalid ones, and overall, the REST method returns an OK
status code. For example:
curl ... -d "{ listenPort: 7007, administrationPort: 'foo' }" -X POST http://localhost:7001/management/weblogic/latest/edit/servers/Server-0 HTTP/1.1 200 OK { messages: [ { severity: "FAILURE", field: "administrationPort", message: "Something about the value needs to be an integer" } ] }
In this example, the listen port is modified and the administration port is not. The method returned an OK
status code.
Using Multiple Edit Sessions
In a previous release, WLS introduced multiple edit sessions. These edit sessions are scoped. There is one scope for domain level edit sessions and one per partition. Each scope has a default edit session. Edit session names are unique within a scope, but not across scopes.
For more information about edit sessions, see Managing Named Concurrent Edit Sessions in Using Oracle WebLogic Server Multitenant.
For all the REST resources in the edit
tree, you must specify which edit session to use—the name of the scope and the name of the edit session within that scope.
The edit session scope name is derived from the URL. If you use a non-partitioned REST URL, then REST uses the domain level scope. If you use a partitioned REST URL, then REST uses that partition's scope.
Within that scope, REST must know which edit session to use. You can either specify a header which states exactly which edit session to use, or you can let REST use defaulting rules to pick one.
Client Specified Edit Session
You can select the edit session by including a weblogic.edit.session
header in the request. The header's value is used as the edit session name. For example:
curl ... -H weblogic.edit.session=MySession ...
Each edit session scope has a default edit session named default
. To explicitly select the scope's default edit session:
curl ... -H weblogic.edit.session=default ...
The Default Edit Session
If you did not include the weblogic.edit.session
header, the REST resources use the following rules to select an edit session:
-
If you currently have one edit session locked in the scope, REST will use it.
-
Or, if you have created one edit session in the scope, REST will use it.
-
Otherwise, REST will use the scope's default edit session.
Creating WLS Configuration Beans
You create a new WLS configuration bean by calling POST
with a JSON structure containing the new bean's properties.
To make this easier, you can use the corresponding create form resource to retrieve a template JSON structure that is populated with default values for the various writeable properties.
URLs For Creating WLS Configuration Beans
To create a collection child, call POST
on the collection's URL, for example, http://localhost:7001/management/weblogic/latest/edit/servers
.
To create an optional singleton child, call POST
on the proposed child's URL, for example, http://localhost:7001/management/weblogic/latest/edit/securityConfiguration/realms/myRealm/adjudicator
.
To retrieve a create form, call GET
on the corresponding create form resource, for example:
http://localhost:7001/management/weblogic/latest/edit/serverCreateForm
And
http://localhost:7001/management/weblogic/latest/edit/securityConfiguration/realms/myRealm/adjudicatorCreateForm
Getting a JSON Template
The underlying WLS beans have default values for many properties. You typically want to display these default values and perhaps, customize them, then use them to create a new WLS bean. You can get these default values by calling GET
on the corresponding create form resource. For example:
curl ... -X GET http://localhost:7001/management/weblogic/latest/edit/serverCreateForm HTTP/1.1 200 OK { listenPort: 7001, ... } }
Creating the Bean
To create the WLS configuration bean, call POST
on a JSON object containing the new bean's properties.
The JSON object does not need to include all the possible properties. Unspecified properties are set to their default values. All collection children need to be assigned a unique identity within their collection, for example, a server needs a unique name. Therefore, the identity
property is not optional.
The response contains a location
header containing the resource's URL. For example:
curl ... -d "{ name: "Server-1", defaultProtocol: "t3s" }" -X POST http://localhost:7001/management/weblogic/latest/edit/servers HTTP/1.1 201 Created Location: http://localhost:7001/management/weblogic/latest/edit/servers/Server-1 curl -X GET http://localhost:7001/management/weblogic/latest/edit/servers/id/Server-1 HTTP/1.1 200 OK { item: { identity: [ "domain", "servers", "Server-1" ], name: "Server-1", defaultProtocol: "t3s", // specified by the caller listenAddress: 7001 // not specified by the caller, therefore set to its default value } }
If a bean with that name already exists, the resource returns a BAD_REQUEST
status code along with a failure message. For example:
curl ... -d "{ name: "Server-1" }" -X POST http://localhost:7001/management/weblogic/latest/edit/servers HTTP/1.1 400 Bad Request { type: "http://oracle/TBD/WlsRestMessageSchema", title: "FAILURE", detail: "Bean already exists: \"weblogic.management.configuration.ServerMBeanImpl@31fa1656([mydomain]/Servers[Server-1])\"", status: 400 }
Similar to updating a WLS configuration bean, you can pass in a mixture of valid and invalid values. Read-only properties and properties that the bean does not support are ignored. If there is an exception setting a property, the resource adds a failure message to the response. After processing all of the properties, if there were any errors, the resource attempts to delete the new bean and returns a BAD_REQUEST
status code.
Example 3-1 Mixture of valid and invalid properties
curl ... -d "{ name: "Server-1", listenPort: abc, defaultProtocol: "no-such-protocol", adminstrationProtocol: "iiop" }" -X POST http://localhost:7001/management/weblogic/latest/edit/servers HTTP/1.1 400 Bad Request { type: "http://oracle/TBD/WlsRestMessagesSchema", title: "ERRORS", status: 400, wls:errorsDetails: [ { type: "http://oracle/TBD/WlsRestMessageSchema", title: "FAILURE", detail: "no-such-protocol is not a legal value for DefaultProtocol.\ The value must be one of the following: [t3, t3s, http, https, iiop, iiops]", o:errorPat: "defaultProtocol" }, { type: "http://oracle/TBD/WlsRestMessageSchema", title: "FAILURE", detail: "Type mismatch. Cannot convert abc to int", o:errorPath: "listenPort" } ] }
Example 3-2 All valid properties
curl ... -d "{ name: "Server-1", listenPort: 7003, defaultProtocol: "https", adminstrationProtocol: "iiop" }" -X POST http://localhost:7001/management/weblogic/latest/edit/servers HTTP/1.1 201 Created Location: http://localhost:7001/management/weblogic/latest/edit/servers/Server-1
Deleting WLS Configuration Beans
To delete a WLS bean (both collection children and optional singleton children), invoke the HTTP DELETE
operation on its corresponding REST URL. Any references to that bean will be removed also. For example, to delete a server:
curl ... -X DELETE http://localhost:7001/management/weblogic/latest/edit/servers/Server-0
Managing Whether a Property Is Set
An MBean property can either be set or unset. If it is set, its value is persisted (for example, to config.xml
) and locked in. If it is unset, then a default value is used. The value can either be the default value for the property's type, a hard coded default value, or a computed default value that runs some custom Java code.
By default, when you call GET
on a resource, it returns the property's current value. When you set the value of a String
property to null or an empty string, it unsets the property (returns it to its default value).
REST lets you determine whether a property has been set, and explicitly set or unset a property.
If you set the expandedValues
query parameter to true
when getting a resource, each value is returned as a JSON object with a set
Boolean property and a value
property that holds the current value. For example, getting a server returns:
curl ... -X GET \ http://localhost:7001/management/weblogic/latest/edit/servers/myserver?&expandedValues=true { listenPortEnabled: { set: false, value: true }, // currently not set name: { set: true, value: "myserver" }, // currently set listenPort: { set: true, value: 7003 } // currently set }
Similarly, you can use the expandedValues
query parameter to explicitly set or unset values. For example, to unset the listen port and set the listen address to an empty string:
curl ... -d "{ listenPort: { set: false }, // value will be ignored if specified listenAddress: { set: true, value: "" } }" -X POST http://localhost:7001/management/weblogic/latest/edit/servers/myserver?expandedValues=true
Invoking Operations
Each WLS bean operation maps to its own REST URL. In the case of overloaded operations (for example, shutdown()
versus shutdown(int, boolean))
, all the overloaded operations map to the same URL and the resource looks at the incoming arguments to determine which operation to invoke.
If the operation requires input arguments, they are specified by passing in a JSON object request body with a property for each argument. The name of the property matches the name of the argument.
If the operation does not take input arguments, you must pass in a JSON object with no properties.
Similarly, if the operation returns a value, then it is returned in a standard REST response body's JSON object return
property. If the operation is void, the response body does not include an return
property.
If the underlying MBean operation throws an exception, the REST method returns a BAD REQUEST
(404
) response containing the exception's text.
Example 3-3 void operation with no arguments : void shutdown()
curl ... -d "{}" \ -X POST http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/shutdown { // response does not include a 'return' property since it's a void operation }
Example 3-4 void operation with multiple arguments : void shutdown(int timeout, boolean ignoreSessions)
curl ... -d "{ timeout: 500, ignoreSessions: false }" \ -X POST http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/shutdown { // response does not include a 'return' property since it's a void operation }
Example 3-5 non-void operation with an argument: String getURL(String protocol)
curl ... -d "{ protocol: 'http' }" \ -X POST http://localhost:7001/management/weblogic/latest/domainRuntime/serverRuntimes/Server-0/getURL { return: "http://localhost:7003" }
Using Queries
The REST API includes a powerful bulk access capability that lets you dynamically describe a tree of beans that can be returned in one call.
Each tree (for example, edit, domain runtime, and such), has a root search
resource. You can POST
a query to these search
resources. The query indicates which beans (and properties and links) should be returned, and, as such, returns a portion ("slice") of the bean tree.
Bulk access can only be used for reading; it cannot be used for writing.
Search Resources
Each bean tree includes a search
resource for bulk queries.
On the Administration Server:
URL | Description |
---|---|
|
Returns a slice of the edit bean tree (in progress edits that have not been saved to disk yet). |
|
Returns a slice of the last configuration bean tree that was saved to disk (versus the configuration the servers are currently using). |
|
Returns a slice of the Administration Server's domain runtime bean tree (which covers all the servers' runtime bean trees). |
|
Returns a slice of the Administration Server's configuration bean tree (the configuration the Administration Server is running against). |
|
Returns a slice of the Administration Server's runtime bean tree. |
On Managed Servers:
URL | Description |
---|---|
|
Returns a slice of Managed Server's configuration bean tree (the configuration the server is running against). |
|
Returns a slice of the Managed Server's runtime bean tree. |
When you POST
a query to a search resource, the query starts searching at the root bean of the tree. The resource returns a JSON response containing the results of the query, that "slice" of the bean tree.
Object Queries
An object query describes what data should be returned for a WLS bean (or collection of beans), such as:
-
Which of the bean's properties should be returned.
-
Which of the bean's links should be returned.
-
Which of the bean's children should be returned.
-
For a collection, which of its children should be returned.
Note that all searches start at the root bean of the search
resource's tree. For example, if you POST
a query to management/weblogic/latest/domainRuntime/search
, it starts searching at the DomainRuntimeMBean
in the domain runtime tree.
Fields and ExcludeFields
fields
specifies which bean properties (for example, scalars and references) are returned. It is a JSON string array of property names. For example, to return the domain's name
and configurationVersion
:
curl ... -d "{ fields: [ 'name', 'configurationVersion' ] }" \ -X POST http://localhost:7001/management/weblogic/latest/edit/search
If the query lists properties that the bean does not support, then that part of the query is ignored (instead of returning an error). If fields
is not specified, then all of the properties are returned.
excludeFields
specifies a list of fields that should not be returned; all other properties are returned. fields
and excludeFields
are mutually exclusive.
Note that a query's fields
and excludeFields
properties mirror the fields
and excludeFields
query parameters that you can specify when calling GET
on a resource. The difference is that the query parameters use comma-separated names and queries use JSON arrays of names.
Links and ExcludeLinks
links
specifies which of the bean's links should be returned. It is a JSON string array of link rel
names. For example, to return the domain's self
and servers
links:
curl ... -d "{ links: [ 'self', 'servers' ] }" \ -X POST http://localhost:7001/management/weblogic/latest/edit/search
If the query lists links that the bean does not support, then that part of the query is ignored (instead of returning an error).
If links
is not specified, then all the links are returned (except for collection children, which only return their self
and canonical
links by default).
Similarly, excludeLinks
specifies a list of links that should not be returned; all other links are returned. links
and excludeLinks
are mutually exclusive.
To return all of a collection's children's links, use excludeLinks
: []
.
Note that a query's links
and excludeLinks
properties mirror the links
and excludeLinks
query parameters that you can specify when calling GET
on a resource.
Children
children
specifies which child bean properties are returned. It is a JSON object whose property names are the names of the children to return, and whose values are object queries. For example, to get the domain's name, along with the name and listen port of each server:
curl ... -d "{ fields: [ 'name' ], // only return the domain's name children: { servers: { // fetch the domain's 'servers' collection fields: [ 'name', 'listenPort' ] // only return each server's name and listen port } } }" -X POST http://localhost:7001/management/weblogic/latest/edit/search
If children
is not specified, then none of the bean's children are returned.
Identities
Sometimes you want to only return certain items in a collection (for example, myserver
and Server-0
). Each collection child has a property that specifies its identity. Typically this is the name
property. The query uses this property name to specify which children of a collection are returned. It is a JSON string array of identities. fields
and links
can also be used to control which properties and links are returned for each of these children. For example, to return the name and listen port for the servers, Server-0
and Server-1
:
curl ... -d "{ fields: [ 'name' ], // only return the domain's name children: { servers: { // fetch the domain's 'servers' collection names: [ 'Server-0', 'Server-1' ], // only return the children whose 'name' is 'Server-0' or 'Server-1' fields: [ 'name', 'listenPort' ] // only return each server's name and listen port } } }" -X POST http://localhost:7001/management/weblogic/latest/edit/search
Identities that do not exist are ignored (instead of returning an error). Similarly, if the context is not a collection, then this part of the query is ignored. By default, all collection children are returned.
Response Body
The response body follows the usual pattern (inline properties or items
, depending on whether the URL is for a bean or a collection). The child beans are returned as nested properties. For example:
curl ... -d "{ fields: [], // don't return any domain level properties links: [], // don't return any domain level links children: { servers: { // fetch the domain's 'servers' collection names: [ 'Server-0', 'Server-1' ], // only return the children whose 'name' is 'Server-0' or 'Server-1' fields: [ 'name' ], // only return each server's name links: [], // don't return any per-server links children: { SSL: { fields: [ 'listenPort' ], // only return each server's SSL listen port links: [] // don't return any SSL level links } } } } }" -X POST http://localhost:7001/management/weblogic/latest/edit/search {code:JavaScript} HTTP/1.1 200 OK { servers: { items: [ { name: "myserver", SSL: { listenPort: 7002} }, { name: "AnotherServer", SSL: { listenPort: 7002} } ] } }
Query Examples
This example gets the component runtimes of specific applications on all running servers. It only returns the name for the server runtimes and application runtime parents and returns all of the component runtimes' properties.
curl ... -d "{ fields: [], links: [], // don't return any domain runtime level properties or links children: { serverRuntimes: { fields: [ 'name' ], links: [], // return each server's name. don't return any server level links children: { applicationRuntimes: { name: [ 'myapp', 'BasicApp' ], // only return apps 'myapp' and 'BasicApp' fields: [ 'name' ], links: [], // return each app's name but no per-app links children: { componentRuntimes: { links: [] } // return all component runtime properties, but no links } } } } } }" -X POST http://localhost:7001/management/weblogic/latest/domainRuntime/search
This example gets all of the servlet runtime and EJB runtime information for a set of applications across all running servers.
curl ... -d "{ links: [], fields: [], children: { serverRuntimes: { links: [], fields: [ 'name', 'state' ], children: { applicationRuntimes: { name: [ 'myapp', 'BasicApp' ], links: [], fields: [ 'name', 'healthState' ], children: { componentRuntimes: { links: [], fields:[ 'name', 'healthState', 'contextRoot', 'openSessionsCurrentCount', 'sessionsOpenedTotalCount' ], children: { EJBRuntimes: { links: [], fields: [ 'EJBName', 'type' ], children: { transactionRuntime: { links: [], fields: [ 'transactionsCommittedTotalCount', 'transactionsRolledBackTotalCount', 'transactionsTimedOutTotalCount' ] }, poolRuntime: { links: [], fields: [ 'accessTotalCount', 'missTotalCount', 'destroyedTotalCount', 'pooledBeansCurrentCount', 'beansInUseCurrentCount', 'waiterCurrentCount', 'timeoutTotalCount' ] }, cacheRuntime: { links: [], fields: [ 'cachedBeansCurrentCount', 'cacheAccessCount', 'cacheMissCount', 'activationCount', 'passivationCount' ] }, lockingRuntime: { links: [], fields: [ 'lockEntriesCurrentCount', 'lockManagerAccessCount', 'waiterTotalCount', 'waiterCurrentCount', 'timeoutTotalCount' ] }, timerRuntime: { links: [], fields: [ 'timeoutCount', 'cancelledTimerCount', 'activeTimerCount', 'disabledTimerCount' ] } } }, servlets: { links: [], fields: [ 'servletName', 'contextPath', 'reloadTotalCount', 'invocationTotalCount', 'executionTimeTotal', 'executionTimeHigh', 'executionTimeLow' ] } } } } } } } } }" -X POST http://localhost:7001/management/weblogic/latest/domainRuntime/search
Limiting the Wait Time For a Delegated Request
When you make a GET request or a search POST call in the domainRuntime tree that gets delegated to one or more servers, you can specify the requestMaxWaitMillis
query parameter which sets the maximum amount of time you are willing to wait for a response from each server. If not specified, it uses the RestfulManagementServicesMBean's DelegatedRequestMaxWaitMillis
value that the administrator configured for the domain.
For servers that do not respond fast enough, the response body includes bad per-server HTTP status codes.
Examine the following examples:
# GET all the server runtimes' names, give up on a server if it doesn't respond within 10 milliseconds: curl -v \ --user admin:admin123 \ -H X-Requested-By:MyClient \ -H Accept:application/json \ -H Content-Type:application/json \ -X GET http://127.0.0.1:7001/management/weblogic/latest/domainRuntime/serverRuntimes?links=none\&fields=name\&requestMaxWaitMillis=10 < HTTP/1.1 200 OK {"items": [ { "httpStatus": 504, "name": "Cluster1Server1", "identity": [] }, {"name": "AdminServer"}, { "httpStatus": 504, "name": "Cluster1Server2", "identity": [] } ]} # GET all the server runtimes' application's names, give up on a server if it doesn't respond within 50 milliseconds: curl -v \ --user admin:admin123 \ -H X-Requested-By:MyClient \ -H Accept:application/json \ -H Content-Type:application/json \ -X POST http://127.0.0.1:7001/management/weblogic/latest/domainRuntime/search?requestMaxWaitMillis=50 \ -d "{ links: [], fields: ['name'], children: { serverRuntimes: { links: [], fields: ['name'], children: { applicationRuntimes: { links: [], fields: ['name'] } } } } }" < HTTP/1.1 200 OK { "name": "bean-ex", "serverRuntimes": {"items": [ { "httpStatus": 504, "name": "Cluster1Server1", "identity": [] }, { "name": "AdminServer", "applicationRuntimes": {"items": [ {"name": "bea_wls_management_internal2"}, {"name": "jms-internal-xa-adp"}, {"name": "mejb"}, {"name": "jms-internal-notran-adp"}, {"name": "bea_wls_internal"}, {"name": "wls-management-services"}, {"name": "bea_wls_deployment_internal"} ]} }, { "httpStatus": 504, "name": "Cluster1Server2", "identity": [] } ]} }
Consolidating Search Results
You can consolidate the domainRuntime search results of REST resources that span multiple servers in a domain based on criteria you specify, for example, you can retrieve the maximum openSocketsCurrentCount
of all the running servers.
Like any search, you use the request body to specify a slice of the bean tree to return. To enable this feature, you specify additional fields to indicate that the results should be consolidated across the servers and how each property should be consolidated.
Review the syntax for the following consolidated search examples:
---------------------------------------------------------------------- Get the total number of open sessions across each application's component runtimes across all servers ---------------------------------------------------------------------- curl -v \ --user monitor:monitor123 \ -H X-Requested-By:MyClient \ -H Accept:application/json \ -H Content-Type:application/json \ -d "{ links: [], fields: [], children: { serverRuntimes: { mergeCollection: true, children: { applicationRuntimes: { mergeOn: 'name', fields: [ { name: 'name', sameValue: true } ], children: { componentRuntimes: { mergeCollection: true, fields: [ { name: 'openSessionsCurrentCount', total: true } ] } } } } } } }" \ -X POST http://localhost:7001/management/weblogic/latest/domainRuntime/search HTTP/1.1 200 OK Response Body: {"serverRuntimes": {"items": [{"applicationRuntimes": {"items": [ { "name": "JDBCDataSource1", "componentRuntimes": {"items": [{}]} }, { "name": "bea_wls_deployment_internal", "componentRuntimes": {"items": [{"openSessionsCurrentCount": { "total": 0, "count": 3 }}]} }, { "name": "wls-management-services", "componentRuntimes": {"items": [{"openSessionsCurrentCount": { "total": 202, "count": 3 }}]} }, { "name": "bea_wls_cluster_internal", "componentRuntimes": {"items": [{"openSessionsCurrentCount": { "total": 0, "count": 2 }}]} }, { "name": "jms-internal-xa-adp", "componentRuntimes": {"items": [{}]} }, { "name": "fairShare", "componentRuntimes": {"items": [{"openSessionsCurrentCount": { "total": 0, "count": 2 }}]} }, { "name": "bea_wls_internal", "componentRuntimes": {"items": [{"openSessionsCurrentCount": { "total": 0, "count": 3 }}]} }, { "name": "JMSSystemResource1", "componentRuntimes": {"items": [{}]} }, { "name": "basicapp", "componentRuntimes": {"items": [{"openSessionsCurrentCount": { "total": 0, "count": 2 }}]} }, { "name": "jms-internal-notran-adp", "componentRuntimes": {"items": [{}]} }, { "name": "bea_wls_management_internal2", "componentRuntimes": {"items": [{"openSessionsCurrentCount": { "total": 0, "count": 1 }}]} }, { "name": "mejb", "componentRuntimes": {"items": [{}]} } ]}}]}} ---------------------------------------------------------------------- Get the total number of invocations of the servlets of each component runtime of the fairShare and wls-management-services applications across all servers ---------------------------------------------------------------------- curl -v \ --user monitor:monitor123 \ -H X-Requested-By:MyClient \ -H Accept:application/json \ -H Content-Type:application/json \ -d "{ links: [], fields: [], children: { serverRuntimes: { mergeCollection: true, children: { applicationRuntimes: { name: [ 'fairShare', 'wls-management-services' ], mergeOn: 'name', fields: [ { name: 'name', sameValue: true } ], children: { componentRuntimes: { mergeOn: 'moduleId', fields: [ { name: 'contextRoot', sameValue: true } ], children: { servlets: { mergeCollection: true, fields: [ { name: 'invocationTotalCount', total: true } ] } } } } } } } } }" \ -X POST http://localhost:7001/management/weblogic/latest/domainRuntime/search HTTP/1.1 200 OK Response Body: {"serverRuntimes": {"items": [{"applicationRuntimes": {"items": [ { "name": "fairShare", "componentRuntimes": {"items": [{ "contextRoot": "\/fairShare", "servlets": {"items": [{"invocationTotalCount": { "total": 0, "count": 8 }}]} }]} }, { "name": "wls-management-services", "componentRuntimes": {"items": [{ "contextRoot": "\/management", "servlets": {"items": [{"invocationTotalCount": { "total": 202, "count": 9 }}]} }]} } ]}}]}}
The first example, "Get the total number of open sessions across each application's component runtimes across all servers,” keeps each application separate (based on the application's name
), merging each application's components together across all the servers.
This is achieved by specifying:
serverRuntimes - mergeCollection: true applicationRuntimes - mergeOn: 'name' componentRuntimes - mergeCollection: true
For example, if the bean tree has:
server1 app1 : comp1, comp2 app2 : comp3, comp4 app3 : comp5, comp6 server2 app1 : comp1, comp2 app2 : comp3, comp4 app3 : comp5, comp6
The response will return:
app1 comp merged values from server1.app1.comp1, server1.app1.comp2, server2.app1.comp1, server2.app1.comp2 app2 comp merged values from server1.app2.comp3, server1.app2.comp4, server2.app2.comp3, server2.app2.comp4 app3 comp merged values from server1.app3.comp5, server1.app3.comp6, server2.app3.comp5, server2.app3.comp6
The second example, "Get the total number of invocations of the servlets of each component runtime of the fairShare and wls-management-services applications across all servers," keeps each application separate (based on the application's name
), and keeps each application's components separate (based on the component's moduleId
), merging each application's component's servlets together across all the servers. It also specifies to return results only for app1
and app2
(versus all the applications).
This is achieved by specifying:
serverRuntimes - mergeCollection: true applicationRuntimes - mergeOn: 'name', name: [ 'app1', 'app2' ] componentRuntimes - mergeOn: 'moduleId' servlets - mergeCollection: true
For example, if the bean tree has:
server1 app1 comp1 : servlet1, servlet2 comp2 : servlet3, servlet4 app2 comp3 : servlet5, servlet6 comp4 : servlet7, servlet8 app3 comp5 : servlet9, servlet10 comp6 : servlet11, servlet12 server2 app1 comp1 : servlet1, servlet2 comp2 : servlet3, servlet4 app2 comp3 : servlet5, servlet6 comp4 : servlet7, servlet8 app3 comp5 : servlet9, servlet10 comp6 : servlet11, servlet12
The response will return (notice that app3
isn't returned):
app1 comp1 merged values from server1.app1.comp1.servlet1, server1.app1.comp1.servlet2, server2.app1.comp1.servlet1, server2.app1.comp1.servlet2 comp2 merged values from server1.app1.comp2.servlet3, server1.app1.comp2.servlet4, server2.app1.comp2.servlet3, server2.app1.comp2.servlet4 app2 comp3 merged values from server1.app2.comp3.servlet5, server1.app2.comp3.servlet6, server2.app2.comp3.servlet5, server2.app2.comp3.servlet6 comp4 merged values from server1.app2.comp4.servlet7, server1.app2.comp4.servlet8, server2.app2.comp4.servlet7, server2.app2.copm4.servlet8
For more examples of consolidating search results in domains and partitions, see Domain Level REST API Examples and Partition Specific REST API Examples (Deprecated).
Request Body Merge-Related Fields
Field | Description |
---|---|
|
Indicates that a collection of MBeans (and their trees of sub-MBeans) should be merged together into a single consolidated MBean tree (and tree of sub-MBeans). Its value is a Boolean. |
|
Indicates when child MBeans in a merged collection should be merged together (for example, that app1 in server1 should be merged with app1 in server2). Its value is a string, naming a property.
|
|
Specifies which properties of an MBean should be returned. fields: [ { name: 'openSessionCurrentCount', total: true, min:true, max:true }, { name: 'type', sameValue: true } ] Multiple merge rules can be specified for the same property (for example, return the min, max, and total). Returns BAD REQUEST if no merge rules are specified for a property. See the Per-Property Merge Rules table below. |
|
Specifies which properties should not be returned when doing a non-consolidated search (for example, a list of what not to return instead of what to return). It is not supported when doing consolidated searches. Returns BAD REQUEST if present. |
|
|
Per-Property Merge Rules
The following table describes the per-property merge rules.
Field | Description |
---|---|
|
Contains the name of the property to merge. It is a mandatory string field. Returns BAD REQUEST if it is not specified. |
|
The Returns BAD REQUEST if the REST API finds a value that is not a number (or a string that can be converted to a number). |
|
Some property values should be the same on each merged MBean, for example, a component's type and moduleId. The Returns BAD REQUEST if the REST API finds different values while merging. Similarly, returns BAD REQUEST if the property value is not a string. |
|
Indicates that the list of property values should be returned. They are unordered. The field is an optional Boolean which defaults to false. It can be used for any type of MBean property. |
About Synchronous and Asynchronous Operations
Several MBean operations (for example, server lifecycle, deployment) are asynchronous. They return job MBeans that must be monitored to determine when the job has completed.
Asynchronous MBean operations return a 200 OK
, 201 Created
or 400 Bad Request
if the operation completed or failed immediately. Otherwise, they return a 202 Accepted
and you must poll the returned job resource to find out when the work is done. By default, REST makes a best effort attempt to wait for the work to complete, but returns after about 5 minutes. You can specify the Prefer
header to control how long REST waits for the work to complete.
Table 3-1 describes using the Prefer
header.
Table 3-1 Using the Prefer Header
Header | Description |
---|---|
|
The client polls a returned job resource. REST returns a |
For example, |
The REST resource internally polls the job for up to the specified number of seconds and returns a |
If you don't specify the Prefer
header, REST will return a 200 OK
, 201 Created
, or 400 Bad Request
if the asynchronous MBean operation finishes within approximately 5 minutes, otherwise it returns a 202 Accepted
.
If you specify both respond-async
and wait
, respond-async
is ignored.
For examples of synchronous and asynchronous operations, see Domain Level REST API Examples and Partition Specific REST API Examples (Deprecated).
Deploying Applications and Libraries
You view deployed applications and libraries in the edit tree. You call POST
on the collections to deploy them, and DELETE
to undeploy them.
Similarly, the deployment MBeans take server relative pathnames. In addition, you can upload files from the client to the server then deploy them and use create form resources to inspect deployments (for example, to determine their preferred name and version numbers). For examples of deploying domain-scoped and partition-scoped applications, see Domain Level REST API Examples and Partition Specific REST API Examples (Deprecated).