<?xml version="1.0" encoding="ISO-8859-1"?>
<!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2018 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->
<refentry id="me_uddi_save_business">
  <refmeta>
    <refentrytitle>uddi_save_business</refentrytitle>
    <refmiscinfo>uddi</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>uddi_save_business</refname>
    <refpurpose>Save or update information about a complete <parameter>businessEntity</parameter> structure.</refpurpose>
  </refnamediv>
  <refsect1 id="syntax_uddi_save_business"><title>Syntax</title>
    <screen>
&lt;uddi_save_business
  generic="1.0"
  xmlns="urn:uddi-org:api" &gt;
	&lt;authInfo/&gt;
	&lt;businessEntity/&gt;
	[&lt;businessEntity/&gt;...] | &lt;uploadRegister/&gt; [&lt;uploadRegister/&gt;...]
&lt;/uddi_save_business&gt;
  </screen></refsect1>
  <refsect1 id="desc_uddi_save_business"><title>Description</title>
    <para>
The <parameter>uddi_save_business</parameter> message is used to save or update information about a
complete <parameter>businessEntity</parameter> structure.  This message has the broadest scope of
all of the save calls in the publisher's API, and can be used to make
sweeping changes to the published information for one or more <parameter>businessEntity</parameter>
structures controlled by an identity.
  </para></refsect1>
  <refsect1 id="params_uddi_save_business"><title>Attributes &amp; Children</title>
    <para>
Either <parameter>businessEntity</parameter> arguments or
<parameter>uploadRegister</parameter> arguments may be passed in a given
<parameter>uddi_save_business</parameter> message, but not both.  Any
number of <parameter>businessEntity</parameter> or
<parameter>uploadRegister</parameter> values can be passed in a single
save (up to a server-imposed limit), but the two types of parameters may
not be mixed.
  </para>
    <refsect2><title>authInfo</title><para>This required argument is an element that contains an authentication token obtained using the <parameter>get_authToken</parameter> call.</para></refsect2>
    <refsect2><title>businessEntity</title><para>One or more complete <parameter>businessEntity</parameter> structures can be passed.  These
structures can be obtained in advance by using the <parameter>get_businessDetail</parameter>  call
or by any other means.</para></refsect2>
    <refsect2><title>uploadRegister</title><para>one or more resolvable HTTP URL addresses that each point to a single and
valid <parameter>businessEntity</parameter> or <parameter>businessEntityExt</parameter> structure.  This variant argument
allows a registry to be updated to reflect the contents of an XML document
that is URL-addressable.  The URL must return a pure XML document that only
contains a <parameter>businessEntity</parameter> structure as its top-level element, and be
accessible using the standard HTTP-GET protocol.</para></refsect2>
    <refsect2><title>Behavior</title><para>If any of the <parameter>uuid_key</parameter> values within in a <parameter>businessEntity</parameter> structure (e.g.
any data with a key value regulated by a <parameter>businessKey</parameter>, <parameter>serviceKey</parameter>, <parameter>bindingKey</parameter>,
or <parameter>tModelKey</parameter>) is passed with a blank value, this is a signal that the data
that is so keyed is being inserted.  This does not apply to structures that
reference other keyed data, such as <parameter>tModelKey</parameter> references within <parameter>bindingTemplate</parameter>
or <parameter>keyedReference</parameter> structures, since these are references.</para></refsect2>
    <para>
To make this call perform an update to existing registered data,
the keyed entities (<parameter>businessEntity</parameter>, <parameter>businessService</parameter>, <parameter>bindingTemplate</parameter> or
<parameter>tModel</parameter>) should have <parameter>uuid_key</parameter>
values that correspond to the registered data.
</para>
<para>
Data can be deleted with this call when registered information is
different from the new information provided. Any <parameter>businessService</parameter>
or <parameter>bindingTemplate</parameter> structures that are found in the
controlling  server but that are missing from the
<parameter>businessEntity</parameter> information provided
in or referenced by this call will be deleted from the registry after
processing this call.
</para>
<para>
Data contained within one or more <parameter>businessEntity</parameter> structures
can be rearranged with this function when data passed to this function
redefines parent container relationships for other registered information.
For instance, if a new <parameter>businessEntity</parameter> is saved with information about a
<parameter>businessService</parameter> that is registered already as part of a separate <parameter>businessEntity</parameter>,
the <parameter>businessService</parameter> is moved from its current container
to the new <parameter>businessEntity</parameter>.  This only applies if
the entity controlling the data referenced is the same entity identified
in the <parameter>uddi_save_business</parameter> message.
  </para><para>
If the file located by the <parameter>uploadRegister</parameter> URL is an extended business
entity (<parameter>businessEntityExt</parameter>) structure, only the <parameter>businessEntity</parameter> data found
within that structure will be registered.
  </para><para>
If a <parameter>businessEntity</parameter> element is used to save data,
then the UDDI-enabled server will create a
URL specific to that server.  This URL can be used to retrieve
via HTTP-GET the <parameter>businessEntity</parameter> structure being registered.  This
information will be added &mdash; if not already present &mdash; to the <parameter>discoveryURL</parameter>'s
collection automatically with a <parameter>useType</parameter> value of <parameter>businessEntity</parameter>.
  </para>
  </refsect1>
  <refsect1 id="ret_uddi_save_business"><title>Return Types</title>
    <para>
This message returns a <parameter>businessDetail</parameter> message that reflects the new registered information for the <parameter>businessEntity</parameter>
information provided.
  </para>
  </refsect1>
  <refsect1 id="errors_uddi_save_business"><title>Errors</title>
    <para>
If an error occurs in processing this message, a <parameter>dispositionReport</parameter> structure
will be returned to the caller in a SOAP Fault. The following error
information will be relevant:
  </para>
    <table><title>Errors signalled by uddi_save_business</title>
      <tgroup cols="2">
       <thead><row><entry>Error Code</entry><entry>Description</entry></row></thead>
	<tbody>
	  <row>
	    <entry><errorcode>E_invalidKeyPassed</errorcode></entry>
	    <entry>signifies that one of the <parameter>uuid_key</parameter> values passed did not match with
any known <parameter>serviceKey</parameter> values.  No partial results will be returned; if any
<parameter>serviceKey</parameter> values passed are not valid, this error will be returned.</entry>
	  </row>
	  <row>
	    <entry><errorcode>E_authTokenExpired</errorcode></entry>
	    <entry>signifies that the authentication token value passed in the authInfo argument
is no longer valid because the token has expired.</entry>
	  </row>
	  <row>
	    <entry><errorcode>E_authTokenRequired</errorcode></entry>
	    <entry>signifies that the authentication token value passed in the authInfo argument is
either missing or is not valid.</entry>
	  </row>
	  <row>
	    <entry><errorcode>E_userMismatch</errorcode></entry>
	    <entry>signifies that one or more of the <parameter>uuid_key</parameter> values passed refers to data that is not
controlled by the individual who is represented by the authentication token.</entry>
	  </row>
	  <row>
	    <entry><errorcode>E_operatorMismatch</errorcode></entry>
	    <entry>signifies that one or more of the <parameter>businessKey</parameter> values passed refers to data that
is not controlled by the UDDI-enabled server that received the request
for processing.</entry>
	  </row>
	  <row>
	    <entry><errorcode>E_keyRetired</errorcode></entry>
	    <entry>signifies that the request cannot be satisfied because one or more
<parameter>uuid_key</parameter> values specified has previously been hidden or removed by the
requester.  This specifically applies to the <parameter>tModelKey</parameter> values passed.</entry>
	  </row>
	  <row>
	    <entry><errorcode>E_invalidURLPassed</errorcode></entry>
	    <entry>an error occurred with one of the <parameter>uploadRegister</parameter> URL values.</entry>
	  </row>
	  <row>
	    <entry><errorcode>E_accountLimitExceeded</errorcode></entry>
	    <entry>signifies that user account limits have been exceeded.</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
  </refsect1>
</refentry>