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
GETmethod). -
You must be in the Admin role to write resources (use the
POSTandDELETEmethods) 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:
-
selfandcanonicallinks to itself. -
A link to its parent.
-
A link to its corresponding create form resource if the collection is writable.
-
Nested
selfandcanonicallinks 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:
-
selfandcanonicallinks to itself. -
A link to its parent.
-
A
createlink 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, comp6The 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).