<?xml version='1.0' encoding='UTF-8'?>
<chapter>
  <chapterinfo>
    <keywordset>
      <keyword>a4j:mediaOutput</keyword>
    </keywordset>
  </chapterinfo>
     <table>
	  <title>Component identification parameters </title>
      <tgroup cols="2">
	  <thead>
            <row>
                  <entry>Name</entry>
                  <entry>Value</entry>
            </row>
        </thead>
        <tbody>
          <row>
            <entry>component-type</entry>
            <entry>org.ajax4jsf.MediaOutput</entry>
          </row>
          <row>
            <entry>component-family</entry>
            <entry>org.ajax4jsf.Resource</entry>
          </row>
          <row>
            <entry>component-class</entry>
            <entry>org.ajax4jsf.component.html.MediaOutput</entry>
          </row>
          <row>
            <entry>renderer-type</entry>
            <entry>org.ajax4jsf.MediaOutputRenderer</entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  
  <section>
        <title>Creating the Component with a Page Tag</title>
    <para>Component definition on a page for graphical data output</para>

  <para>
      <emphasis role="bold">Example:</emphasis>
 </para>
    <programlisting role="XML"><![CDATA[<a4j:mediaOutput element="img" cacheable="false" session="true" createContent="#{paintBean.paint}" value="#{paintData}" mimeType="image/png"/>]]></programlisting>

  </section>
  <section>
    <title>Creating the Component Dynamically Using Java</title>

  <para>
      <emphasis role="bold">Example:</emphasis>
 </para>
    <programlisting role="JAVA"><![CDATA[import org.ajax4jsf.component.html.MediaOutput;
...
MediaOutput myMedia = new MediaOutput ();
...
]]></programlisting>
  </section>
      
      <section>
            <title>Details of usage</title>
            <para>
                  The <emphasis role="bold"><property>&lt;a4j:mediaOutput&gt;</property></emphasis> component is used for generating images, videos or sounds on-the-fly. 
                  Let's consider an image creation and generate a JPEG image with verification digits for captcha (the image will include just digits without any graphical noise and distortion). 
            </para>
            <para>
                  Write the following line on the page:
            </para>
                   <programlisting role="XML"><![CDATA[<a4j:mediaOutput element="img" cacheable="false" session="false" createContent="#{mediaBean.paint}" value="#{mediaData}" mimeType="image/jpeg"/>]]></programlisting>
                  
                  <para>
                        As You see from the example above, first it is necessary to specify the kind of media data You want to generate. 
                        This can be done with the help of <emphasis><property>&quot;element&quot;</property></emphasis> attribute, which possible values are <code>img</code>, <code>object</code>, <code>applet</code>, <code>script</code>, <code>link</code> or <code>a</code>.  
                    </para>
                  <para>
                        The <emphasis><property>&quot;cacheable&quot;</property></emphasis> defines whether the response will be cached or not. In our case we don't need our image to be cached, cause we need it to be changed every time we refresh the page. 
                  </para>
            <para>
                  The <emphasis><property>&quot;mimeType&quot;</property></emphasis> attribute defines the type of output content. It is used to define the corresponded type in the header of an HTTP response.  
            </para>
     
            <para>The <emphasis role="bold"><property>&lt;a4j:mediaOutput&gt;</property></emphasis> attribute has two main attributes:</para>
            <itemizedlist>
                  <listitem>
                        <para>
                              <emphasis><property>&quot;createContent&quot;</property></emphasis> specifies a method that will be used for content creating.
                              The method accepts two parameters. 
                              The first one — with an <code>java.io.OutputStream</code> type — is a reference to the stream that should be used for output. 
                              An output stream accepts output bytes and sends them to a recipient. 
                              The second parameter is a reference to the component&apos;s <emphasis><property>&quot;value&quot;</property></emphasis> attribute and has <code>java.lang.Object</code> type. 
                              This parameter contains deserialized object with data specified in the <emphasis><property>&quot;value&quot;</property></emphasis> attribute.
                        </para>
                  </listitem>
                  <listitem>
                        <para>
                              <emphasis><property>&quot;value&quot;</property></emphasis> attribute specifies a bean class that keeps data for transmitting it into a stream in the method specified with <emphasis><property>&quot;createContent&quot;</property></emphasis>      .
                        </para>
                  </listitem>
            </itemizedlist>
          
            <para>
                  Now let's create the <code>MediaBean</code> class and specify there a primitive random-number generator and <code>paint</code> method that will convert the generated numbers into an output stream and give a JPEG image as a result. 
                  The code for <code>MediaBean</code> class is going to look as following:
            </para>
            <para>
                  <emphasis role="bold">Example:</emphasis>
            </para>
            <programlisting role="JAVA"><![CDATA[package demo;

import java.awt.Graphics2D;
import java.awt.image.BufferedImage;
import java.io.IOException;
import java.io.OutputStream;
import java.util.Random;
import javax.imageio.ImageIO;

public class MediaBean {
	public void paint(OutputStream out, Object data) throws IOException{
		Integer high = 9999;
		Integer low = 1000;
		Random generator = new Random();
		Integer digits = generator.nextInt(high - low + 1) + low;
		if (data instanceof MediaData) {            
			MediaData paintData = (MediaData) data;
            BufferedImage img = new BufferedImage(paintData.getWidth(),paintData.getHeight(),BufferedImage.TYPE_INT_RGB);
            Graphics2D graphics2D = img.createGraphics();
            graphics2D.setBackground(paintData.getBackground());
            graphics2D.setColor(paintData.getDrawColor());
            graphics2D.clearRect(0,0,paintData.getWidth(),paintData.getHeight());
            graphics2D.setFont(paintData.getFont());
            graphics2D.drawString(digits.toString(), 20, 35);
            ImageIO.write(img,"png",out);
        }
    }
}]]></programlisting>
            
<para>
      Now it is necessary to create a class that will keep transmissional data that will be used as input data for a content creation method. 
      The code for <code>MediaData</code> class is going to be as following:
</para>
            <note>
                  <title>Note:</title>
                  <para>A bean class transmitted into value should implement <code>Serializable</code> interface in order to be encoded to the URL of the resource. 
            </para>
            </note>
            
            <para>
                  <emphasis role="bold">Example:</emphasis>
            </para>
            <programlisting role="JAVA"><![CDATA[package demo;

import java.awt.Color;
import java.awt.Font;
import java.io.Serializable;

public class MediaData implements Serializable{

    private static final long serialVersionUID = 1L;
    Integer Width=110;
    Integer Height=50;
    Color Background=new Color(190, 214, 248);
    Color DrawColor=new Color(0,0,0);
    Font font = new Font("Serif", Font.TRUETYPE_FONT, 30);
    
    /* Corresponding getters and setters */
    
}]]></programlisting>      
                  
        <para>
              As a result the <emphasis role="bold"><property>&lt;a4j:mediaOutput&gt;</property></emphasis> component will generate the following image that will be updated on each page refresh: 
        </para>          
            <figure>
                  <title>
                        Using the <emphasis role="bold"><property>&lt;a4j:mediaOutput&gt;</property></emphasis> for generating an image for captcha</title>
                  
                  <mediaobject>
                        <imageobject>
                              <imagedata fileref="images/mediaOutput_init.png"/>
                        </imageobject>
                  </mediaobject>
            </figure>          
              
            <para>Hence, when using the component it&apos;s possible to output your data of any type on a page with Ajax requests.</para>
      </section>

  <section>
    <title>Relevant resources links</title>
        <para>
              Vizit the <ulink url="http://livedemo.exadel.com/richfaces-demo/richfaces/mediaOutput.jsf?c=mediaOutput">MediaOutput page</ulink> at RichFaces LiveDemo for more examples of component usage and their sources. 
        </para>
  </section>	  
 
</chapter>