What are the parameters for the Salesforce WebServiceCallout.invoke method?

Question

I would like to know the parameters for the invoke method used by Salesforce to invoke remote web services. I have a service that I'm suposed to be able to invoke, but the service WSDL does not define the security requirements, so I'm hoping I can add that information manually (The services uses WS-Security passed through Soap headers).

Here is what I (think I) know so far:

WebServiceCallout.invoke(
  Class servicePort, //Usually set to "this", contains httpheader info as well as ? 
  request_x, //Request object, defining schema, properties, and field order
  response_map_x, //Response object, defining schema, properties, and field order
  new String[]{
  String endpoint, //Endpoint of the service
  String ?, //what is this?
  String methodSchema, //Schema for the request object?
  String method, //Name of the request method?
  String responseSchema, //Schema for the response object?
  String response, //Name of the response object?
  String responseClass} //Name of the Apex class the response will be converted to
);

Can anyone help fill in the gaps?

Answer 1

Here's what I have discovered so far for WebServiceCallout.invoke:

Object servicePort - A class with the following variables:
  String enpoint_x: containing the service endpoint (not sure if necessary)
  Map<String,String> inputHttpHeaders_x: custom httpHeaders
  Map<String,String> outputHttpHeaders_x: I think this is the httpHeaders that were returned
  String clientCertName_x: Used in configuring an SSL cert?
  String clientCert_x: Used in configuring an SSL cert?
  String clientCertPassword: Used in configuring an SSL cert?
  Integer timeout_x: How long (in milliseconds?) to wait for the response
  String[] ns_map_type_info: The first String is the namespace of the service schema, the second is the name of the object that contains the Apex classes defining the schema objects
Object request_x - The Apex object that will form the XML schema object
Map<String, Object> response_map_x - Object is the object that the result is to be unserialized into. String is the name of Object variable.
String[] {
  endpoint - The service endpoint
  soapAction - If the service call requires a soapAction, put it here. Otherwise leave blank.
  methodSchema - Schema for the request object
  method - Name of the request method
  responseSchema Schema for the response
  responseClass The Apex class that the response will be unserialized into
}

In addition, Soap headers can be inserted by creating an object in the servicePort class as well as a String with the same variable name+"_hns" that specifies the namespace for that object:

public SoapSecurity Security;
private String Security_hns = "Security=http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd";

The apex XML Schema objects should contain variables for each child element (or attribute). Arrays whose variable names match certain patterns define how the object variables are used in the xml.

Given the following example XML:

<foo a="b"><bar>baz</bar></foo>

The Apex classes would be something like this:

public class MyService {
   public class bar {
      public String bar;
      private String[] bar_type_info = new String[] {'bar','http://www.w3.org/2001/XMLSchema','string','0','1','true'};
      private String[] apex_schema_type_info = new String[] {'http://schema.myservice.com', 'false', 'false'};
      private String[] field_order_type_info = new String[] {'bar'};
   }

   public class foo {
      public MyService.bar bar;
      public String a;
      private String[] bar_type_info = new String[] {'bar','http://schema.myservice.com','bar','0','1','true'};
      private String[] a_att_info = new String[] {'a'};
      private String apex_schema_type_info = new String[] {'http://schema.myservice.com','false','false'};
      private String[] field_order_type_info = new String[] {'bar'};
   }
}

Here's a (brief) breakdown of these objects:

If the variable represents another XML element or a text node, then there needs to be a matching _type_info String[] e.g. bar_type_info. The elements of this array are: 1. XML element name 2. Schema 3. XML type 4. minOccurs 5. maxOccurs (set to '-1' for unbounded) 6. isNillable

If the variable represents an attribute, then there must be a matching _att_info String[] e.g. a_type_info. Thise simply contains the XML name of the attribute.

Note that if an class variable name is a reserved word, then _x is appended to it e.g. bar_x. This would affect the other variables names: bar_x_type_info. The Apex Developer's Guide explains their rules for names, but if you are manually creating it, I think you can give it whatever name you want--the arrays determine the XML element name...

I have not found a way to represent a simple XML type that also contains an attribute: e.g.

<foo bar="baz">bar</foo>

The apex_schema_type_info array specifies information about the XML element represented by the class: 1. Schema 2. 'true' if elementFormDefault="qualified" 3. 'true' if attributeFormDefault="qualified"

I'm still rather fuzzy on what 2 and 3 actually do, but it seems to affect how child elements (and attributes) inherit the parent namespace (whether it's implied or must be specified in the resulting XML).

field_order_type_info simply specifies the order of the child elements.

Please feel free to correct or clarify...

Answer 2

There is the Force.com Apex Code Developers Guide - Understanding the Generated Code, but it is currently fairly sparse on details for WebServiceCallout.invoke(...).

There is also Apex Web Services and Callouts, again not any useful details.

Up-voting Ideas: Documentation for WebServiceCallout may help in the long run.

---

Salesforce have just done an opensource release of wsdl2apex on Github, so you can now check to code to see exactly what is occurring. Announcing the Open-Source WSDL2Apex Generator